Schema API Reference

There's two methods for programmatically interfacing with a TakeShape project's schema.

The REST API, /project/{projectId}/schema, is limited to getting and updating the current schema version. It's most useful for manual workflows where you're exporting the current schema, making edits to its contents, and then reimporting it to your project. This is the endpoint that the TakeShape CLI uses to import and export schemas.

The Admin GraphQL API, /project/{projectId}/v3/admin-graphql, provides more robust functionality for fetching the complete version history for a schema, restoring a previous version, and applying partial updates to the project schema. It's most useful for automated workflows where you're making backups or applying the same change to multiple schemas.

Authentication

Your API requests will need to be authenticated with an API Key as a Bearer Token. Learn more about making API requests and creating API keys.

REST API

You can fetch and update your project schema by making REST requests to the /schema endpoint. This means you should send requests to a URL formatted like  https://api.takeshape.io/project/{projectId}/schema.

The endpoint accepts GET and POST requests.

GET

Making a GET request to your schema endpoint will return your project's current schema in JSON format. For this request to succeed, your API token must have permission to export the project.

If the project ID is not provided, or the schema cannot be found, this will return a 4xx error.

POST

Making a POST request to your schema endpoint will update your schema with the contents of your request body, which must be a complete schema in JSON format.

Upon receiving the contents of the request, the schema will be validated. If the provided schema is invalid, the request will return a 4xx response.

GraphQL API

GraphQL operations are available as part of your project's Admin GraphQL API.

Access the Admin API by using the special v3/admin-graphql endpoint. This means that you should send requests to a URL like https://api.takeshape.io/project/{projectId}/v3/admin-graphql.

Or, if you're using the API Explorer, you can append a ?endpoint=v3/admin-graphql query argument to the /api-explorer URL.

The provided input is applied on the existing schema, which means you only need to include properties and values which you'd like to see changed; omitted values will not be removed.

• If the property doesn't already exist, it'll be added with the provided value.
• If the property does already exist, its old value will be overwritten with the provided one.
• To remove a property, provide null as its value.

Queries

tsGetSchemaVersion

This requires a version argument, then returns the contents of the requested schema version.

query ($version: Int!) {
	tsGetSchemaVersion(version: $version) {
		status
		schema {
			...
		}
	}
}

The status value records whether the schema is available or not. Usually, the status will be Schema found. An example of a time when the status will be Schema not found would be when a new schema version is in the process of being saved and uploaded.

tsGetSchemaVersionList

This provides a list of all schema versions in your project, sorted from the newest to the oldest version. It accepts the pagination arguments from and size.

Each schema version list item contains a summary of the schema: it counts the shapes, queries, mutations, and workflows; and provides the defaultLocale.

query ($from: Int, $size: Int) {
	tsGetSchemaVersionList(from: $from, size: $size) {
		total
		items {
			updated
      version
      schemaVersion
      mutationCount
      queryCount
      workflowCount
      shapeCount
      defaultLocale
		}
	}
}

To get the contents of a given schema version, use the version value as an argument to the tsGetSchemaVersion query.

Mutations

tsUpdateSchema

Whenever you want to update an aspect of your schema, you'll use the tsUpdateSchema mutation: 

mutation ($input: TSUpdateSchemaInput!) {
	tsUpdateSchema(input: $input)
}

It requires an input containing the version (the current version of this schema document) and the schemaVersion (the version of the schema format—as of now, it'll always be 3). Then, you can provide any schema properties you'd like to change.

The version number is required to protect against conflicts when multiple project users are editing the schema simultaneously.

{
	"input": {
		"version": 1,
		"schemaVersion": 3, // This will always be 3
		...
	}
}

The schema input is patched on the existing schema, which means you only need to include properties and values which you'd like to see changed; omitted values will not be removed. If the property doesn't already exist, it'll be added with the provided value. If the property does already exist, its old value will be overwritten with the provided one. To remove a property, provide null as its value.

tsRestoreSchemaVersion

This mutation takes a provided schema version number, gets the contents of the schema at that version, and saves a new version of the schema with those contents. As a result, your project's current schema version will be a copy of an historic one.

mutation ($version: Int!) {
	tsRestoreSchemaVersion(version: $version)
}

You can use this to undo a set of changes. This mutation could have potentially destructive consequences, so use it with caution!