1505402 - RFC 128 - 4.2 Changes to taskcluster-lib-urls

Status: RESOLVED FIXED

(Taskcluster :: Services, enhancement)

Description

[Pete Moore [:pmoore][:pete]]

First, a bit of theory...

Client generators need to be able to determine from a reference document, if it is for an interface that they know how to build.

The reference documents declare which schema they comply to (<some url base>/api-reference.json or <some url base>/exchanges-reference.json) via the $schema property.

However, the actual url here is dependent on the deployment (and rightly so, different deployments could be on different versions, and could have customisations that don't exist on other deployments).

Therefore, rather than letting the client generators attempt to establish if the reference document matches one that they know how to work with, it is better to declare in the reference's schema document (api-reference.json / exchanges-reference.json) a name and version for the type of reference it implements e.g. "metadata": {"name": "exchanges", "version": 7}.

However, api-reference.json and exchanges-reference.json have "$schema": "http://json-schema.org/draft-06/schema#" and the draft-06 schema does not have provisions for a metadata property. But, alas, this is not a problem, since it does have provisions for extending the schema definition, by allowing additional properties.

We can therefore create a refined version of the json draft-06 schema document, reference.json, which includes the requirements of http://json-schema.org/draft-06/schema#, but additionally declares a top level metadata required property which contains required properties name and version.

We then update api-reference.json and exchanges-reference.json to use this new $schema reference, and add metadata to both of them:

api-reference.json would have "name": "api", "version": 1 and exchanges-reference.json would have "name": "exchanges", "version": 1.

Finally, we require that if any further reference types are added in the future in addition to the existing api/exchanges reference types, they too must validate against this new reference.json document, which will mean they are forced to provide name/version metadata about what they represent.

Based on all of this, the following changes are then required to taskcluster-lib-urls:

    Method ServicesManifest should be renamed to APIManifest (to be consistent with the naming in this RFC).
    The following new methods should be added, e.g. for go client:

> func APIReferenceSchema(rootURL string, version string) string { .... }
> func ExchangesReferenceSchema(rootURL string, version string) string { .... }

These will return absolute urls to the *-reference.json documents, i.e. approximately following this logic:

> rootURL == 'https://taskcluster.net'
>   ? 'https://schemas.taskcluster.net/v1/base/{api|exchanges}-reference.json'
>   : '${rootURL}/schemas/v1/base/{api|exchanges}-reference.json'

The following method should be added for locating the API manifest schema (api-manifest.json):

> func APIManifestSchema(rootURL string) string { .... }

The following method should be added for locating the reference schema (reference.json):

> func ReferenceSchema(rootURL string) string { .... }

Comment 1

[Dustin J. Mitchell [:dustin] (he/him)]

https://github.com/taskcluster/taskcluster-lib-urls/pull/22

Comment 2

[Dustin J. Mitchell [:dustin] (he/him)]

These changes have landed.  They rename a function (the breaking bit) and add some otherwise-unused functions.  So I'm not going to rush to update everything to the new version.