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!