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

Note, these formats are not completely stable and may change over time, or merge into one.

Reference Manifest

All services are linked in http://references.taskcluster.net/manifest.json. The file contains links to API references (api.json) and to exchange references (exchanges.json). When a service provides both, the latter generally has an "Events" suffix in the name.

The format of these files is given below.

API References

Our API end-points all have a simple URL made up of a baseUrl + route where a few arguments are substituted into the route. The API end-point takes a JSON entity body as input and returns a JSON entity body. Input is always validated before it is accepted, and output is validated before it is returned.

This makes it easy to describe the API end-points in JSON with references to JSON schema files. The reference format looks as follows:

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

The JSON schema for the API reference format is http://schemas.taskcluster.net/base/v1/api-reference.json and references are validated prior to publication.

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
  • 0.2.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.

The JSON schema for the exchanges reference format is published at http://schemas.taskcluster.net/base/v1/exchanges-reference.json. Messages are validated prior to publication.

Note: we do not recommend validation of messages upon consumption, as publishers may upgrade the schema in a backwards compatible way in the future.