Versioning APIs (GQL PAPI)

Query an API's versions

Obtains information on all unique versions of an API. The status field returns the version's lifecycle state ("DRAFT", "ACTIVE", "DEPRECATED"). The endpoints.id field displays the unique ID for each endpoint of each version of the API.

The API ID of the API you want to query must be included in the variables.

query apiVersions($where: ApiVersionWhereInput) {
  apiVersions(where: $where) {
    nodes {
      id
      name
      status
      current
      endpoints {
        id
      }
    }
  }
}

{
  "where": {
    "apiId": "some-api-id"
  }
}

Create a major API version

Use the createApiVersions mutation to create a new major version of your API. In the Variables, you must specify the API's ID and the new version's name. The new API version's versionStatus will be "draft".

mutation createApiVersions($apiVersions: [ApiVersionCreateInput!]!) {
  createApiVersions(apiVersions: $apiVersions) {
		id
		api
		current
		name
		status
		keywords
		createdAt
		updatedAt
		visibility
		webhooks
		targetGroupId
		versionStatus
		apiVersionType
		spec
  }
}

{
  "apiVersions": {
    "api": "api_[YOUR API ID]",
    "name": "[NEW VERSION NAME]"
  }
}

Create a major version of a GraphQL API using introspection

Use the createGqlApiVersions mutation to create a major version of an existing GraphQL API and using introspection to populate the GraphQL schema.

In Variables, specify the API ID of the API for which you want to create a major version. Specify the version's name and introspectionCallUrl. Set isIntrospectionCall to true.

mutation CreateGqlApiVersions($gqlApiVersionCreateInput: [GqlApiVersionCreateInput!]!) {
  createGqlApiVersions(gqlApiVersions: $gqlApiVersionCreateInput) {
    id
    versionStatus
  }
}

{
  "gqlApiVersionCreateInput": {
    "api": "YOUR API ID",
    "name": "v3",
    "introspectionCallUrl": "YOUR BASE URL",
    "isIntrospectionCall": true
  }
}

Update a major API version

📘

updateApi mutation

Use the updateAPI mutation to change fields that apply across the API, such as its category. The updateApiVersions mutation shown below is used to update fields that apply only to that version.

Use the updateApiVersions mutation to update a specific major version of your API. You must specify the apiVersionId for the version you want to update. Only the following can usually be changed for the API's version:

current - If the API version is ACTIVE and current is set to true, it will become the default version API consumers see.
versionStatus - The version lifecycle state: "draft", "active", "deprecated".
visibility - Set to "PUBLIC" or "PRIVATE".

mutation updateApiVersions($apiVersions: [ApiVersionUpdateInput!]!) {
  updateApiVersions(apiVersions: $apiVersions) {
		id
		api
		current
		name
		versionStatus
		apiVersionType
  }
}

{
  "apiVersions": {
    "apiVersionId": "apiversion_[YOUR VERSION ID]",
    "versionStatus": "active",
    "current": true
  }
}

Updating the schema for a major version of a GraphQL API

Since each version's endpoint ids are unique, you can update the GraphQL schema for a major API version by following the instructions to update a GraphQL API's schema, specifying the endpoint id for the major version.