Viewing and restoring schema versions

Every time a project schema changes, whether you're adding a single field or completely reworking all your shapes, a new version of the schema is created.

We track the entire history of your project schema and make every version available to view, export, and even restore from.

Here, we'll show how you can view and act upon your schema's history from both the web client and the API.

Web Client

View your project's schema history

Your project schema's version history is accessible from the Schema tab. From the Schema tab, navigating to the History link will open your schema history.

On the Schema history page, you'll see a table showing the ten most recent versions. For every version, you'll see its version number, when it was created, the number of objects on it, and how that number has changed since the previous version.

Each schema version also provides two actions: restore and export.

Restoring a schema version

When you restore a previous schema version, a new version is created that copies the version you're restoring against. Schema versions are immutable, meaning we're never updating an old version of the schema, we're always copying a schema, making necessary changes, and saving the new version. This means all previous  versions of your schema still exist and are accessible.

However, it's important to keep in mind that restoring your schema to a different version can potentially changes to your GraphQL API which may introduce downstream breaking changes to any code you've written that depends on a certain state of your API. That's why, after choosing to restore, you'll be prompted with a warning and confirmation dialog about the change you're about to make.

When you're confident to go ahead, click Restore.

After a moment, your project will reload using the restored version and you'll see a newly created version at the top of the history.

Exporting a schema version

Using the export action will download the schema file for that version. You can use this exported version to fork a new empty project, edit the schema file directly and upload your changes via the CLI, or whatever else you like to do with files.

API

Using your project's Admin API, you have access to queries and mutations to view your schema history and restore previous versions. In fact, these are the same exact GraphQL requests that the web client uses!

Query for your project's schema history

The Admin GraphQL mutation tsGetSchemaVersionList will return a list of schema versions with a summary of their contents. It accepts optional pagination arguments from and size to limit the size of your requests. Sorting schemas it not currently supported.

Request

query {
	tsGetSchemaVersionList(size: 10) {
		total
		items {
			updated
	    version
	    schemaVersion
	    mutationCount
	    queryCount
	    workflowCount
	    shapeCount
	    defaultLocale
		}
	}
}

Response

{
  "data": {
    "tsGetSchemaVersionList": {
      "total": 54,
      "items": [
        {
          "updated": "2020-12-01T17:33:31.758Z",
          "version": 54,
          "schemaVersion": "3",
          "mutationCount": 9,
          "queryCount": 4,
          "workflowCount": 0,
          "shapeCount": 16,
          "defaultLocale": "en"
        },
				...
			]
		}
	}
}

Query for a specific schema version

There's a separate query to get the contents of a schema at a given version. For that, use the tsGetSchemaVersion admin query. It requires one argument, a version number.

Request

query {
  tsGetSchemaVersion(version: 54) {
    schema
  }
}

Response

{
  "data": {
    "tsGetSchemaVersion": {
      "schema": {
        "workflows": {},
        "apiVersion": "2",
        "defaultLocale": "en",
        "locales": [
          "en"
        ],
        "projectId": "73e1dce1-77f0-4c3d-86a0-7e3d0389838a",
        "schemaVersion": "3",
        "version": 54,
        ...
		}
	}
}

Restore a specific schema version

To restore your project's schema to a previous version using the API, we provide the tsRestoreSchemaVersion admin mutation. This accepts the version number of the schema you'd like to restore—and returns the version number of the newly created schema.

Request

mutation {
  tsRestoreSchemaVersion(version: 51) {
    version
  }
}

Response

{
  "data": {
    "tsRestoreSchemaVersion": {
      "version": 55
		}
	}
}

Join us

Interested in joining the team as coworker or investor?

contact@takeshape.com