Reference Formats


Most Taskcluster services make heavy use of JSON schemas for validation of incoming and outgoing data, whether through APIs or AMQP exchanges. This makes the external API surface very reliable and consistent, and helps avoid a lot of bugs and typos.

The use of JSON schemas also makes it very easy to generate documentation for all the external interfaces offered by Taskcluster components, as done on this site. To further simplify the generation of documentation and API-clients we have formalized formats for describing interfaces.

This document describes the formats in which references for API end-points and AMQP exchanges are documented. This is useful for automatic generation of:

  • Documentation
  • Client libraries
  • Dummy mock servers

Reference Manifest

All services are linked in a reference manifest, available at /references/manifest.json. The file contains links to API references (api.json) and to exchange references (exchanges.json).

The schema for this manifest is as follows:

Taskcluster Service Manifest (source)

Manifest of taskcluster service definitions available in a taskcluster service deployment. These manifests are served from $ROOT_URL/references/manifest.json.

See https://github.com/taskcluster/taskcluster-references for further information.

servicesArray of
default:

List of services that comprise a taskcluster build.

serviceNamestring^[a-z][a-z0-9_-]*$

A short name for the service, such as queue / purge-cache / ec2-manager. This matches the serviceName field in any references linked from here.

apisArray of
default:

HTTP API exposed by this service.

versionstring^v[0-9][0-9]*$

Version of API, e.g. v1.

referencestring

A document conformant to $ROOT_URL/schemas/common/api-reference-v1.json# describing the API exposed by service.

pulseArray of
default:

Pulse exchanges exposed by this service.

versionstring^v[0-9][0-9]*$

Version of API, e.g. v1.

referencestring

A document conformant to $ROOT_URL/schemas/common/exchanges-reference-v1.json# describing the API exposed by service.

API References

Taskcluster API calls are REST-like HTTP transactions, and the API reference describes how to formulate a request and what to expect in the response. This includes an HTTP method, a route, and (for calls with a request body) an input schema.

The route includes some parameters where user data (such as a taskId) can be substituted. The request URL is formed from the Taskcluster rootUrl, the service name, the API version, and the post-substitution route. Taskcluster-lib-urls provides an api method to perform this operation.

An API end-point can take a JSON entity body as input and return a JSON entity body, both of which are governed by a schema. Input is always validated by the server before it is accepted, and output is validated before it is returned. Note that clients should not re-validate output against the declared schema, as server responses may change by adding additional properties.

The API reference format has the following format:

API Reference File (source)

Reference of methods implemented by API

versioninteger
  • 0

API reference version

$schemastringuri

Link to schema for this reference. That is a link to this very document. Typically used to identify what kind of reference this file is.

titlestring

API title in markdown

descriptionstring

API description in markdown

baseUrlstringuri

BaseUrl for all routes described in this document

serviceNamestring[1:22]^[a-z][a-z0-9_-]*$

Name of service for automation. Will be consumed by client generators to produce URLs

entriesArray of

Array of methods in this reference

typestring
  • function

Type of entry, currently only function.

methodstring
  • get
  • post
  • put
  • head
  • delete
  • options
  • trace
  • copy
  • lock
  • mkcol
  • move
  • purge
  • propfind
  • proppatch
  • unlock
  • report
  • mkactivity
  • checkout
  • merge
  • m-search
  • notify
  • subscribe
  • unsubscribe
  • patch
  • search

HTTP method (verb) used to access the function

routestring

Route for the call, note that arguments wrapped with brackets, like /v1/user/<userId>/ must be replaced. And the route must be appended to the baseUrl

argsArray of

Arguments from route that must be replaced, they'll appear wrapped in brackets inside route.

string

Argument that appears in route warpped in angle brackets. It must be replaced to call the function.

queryArray of

List of accepted query-string parameters, these are always optional.

string

Optional query-string parameter

namestring

Name of the function this is a stable identifier for use in auto-generated client libraries

stabilitystring
  • deprecated
  • experimental
  • stable

Stability level of the API

scopesOne of

Scope expression template specifying required scopes for a method. Not provided if authentication isn't required.

Required-Scopestring^[\x20-\x7e]*$

The most basic element of a scope expression

$ref: #/definitions/scopeExpressionTemplateAnyOf (follow 'source' link above to view)
$ref: #/definitions/scopeExpressionTemplateAllOf (follow 'source' link above to view)
$ref: #/definitions/scopeExpressionTemplateIf (follow 'source' link above to view)
inputstring

JSON schema for input, if input is validated, otherwise not present. The value must be a relative URI, based on the service's schema location; that is, based at <rootUrl>/schemas/<serviceName.

outputOne of
Output Schemastring

JSON schema for output, if output is validated, otherwise not present. The value must be a relative URI, based on the service's schema location; that is, based at <rootUrl>/schemas/<serviceName.

Blobstring
  • blob

Output kind if not JSON matching a specific schema.

titlestring

Title of API entry

descriptionstring

Description (ie. documentation) for the API entry

AMQP Exchange References

Each service which sends Pulse messages has its exchanges and messages defined in a reference document with the following format.

Exchange Reference File (source)

Reference of exchanges published

version
  • 0

Exchange reference version

$schemastringuri

Link to schema for this reference. That is a link to this very document. Typically used to identify what kind of reference this file is.

serviceNamestring[1:22]^[a-z][a-z0-9_-]*$

Name of service for automation. Will be consumed by client generators to produce URLs

titlestring

Title for set of exchanges in markdown

descriptionstring

Description of set of exchanges in markdown

exchangePrefixstring

Prefix for all exchanges described in this document

entriesArray of
typestring

Type of entry, currently only topic-exchange.

exchangestring

Exchange name on AMQP server, must be prefixed with exchangePrefix from this document.

namestring

Name of exchange, this is a stable identifier for use in auto-generated client libraries

titlestring

Title of exchange entry

descriptionstring

Description (ie. documentation) for the exchange

routingKeyArray of
namestring

Identifier usable in client libraries

summarystring

Short description of key in markdown

constantstring

Constant to be used for this field, cannot be overwritten, only present if applicable.

multipleWordsboolean

True, if key may contain dots, which AMQP will consider as words. This determines if # or * should be used in client libraries

requiredboolean

True, if the key is always present, if false the value _ will be used in place when no appropriate value is available for the key.

schemastring

JSON schema for messages on this exchange. The value must be a relative URI, based on the service's schema location; that is, based at <rootUrl>/schemas/<serviceName.

Messages are validated on the server prior to publication. Note that clients should not validate received messages against the declared schema, as messages may change by adding additional properties.

Taskcluster-References

The taskcluster-references service handles collating and serving references and schemas, and also holds the authoritative copy of the schemas linked above.

When these schemas must be modified, new versions will be added, thus changing the $schema URI in the documents. The schemas at the existing URIs will not change.