Web Specifications Reference Server

This is a service that exposes bibliographic references and definition cross-references for use in Web specifications. Bibliographic references are used mostly to generate the references that are used in the footer of specifications. Cross-references are used so that one can reuse terms defined in a specification being referenced while easily providing links to the place at which they are defined.

API

The API to the service is very simple. It supports two operations, each of which takes the same two parameters. CORS is enabled for all origins.

The operations are:

GET http://webref.herokuapp.com/bibrefs
Used to get a set of bibliographic references.
GET http://webref.herokuapp.com/xrefs
Used to get a set of definition cross-references.

The parameters, to be used in the query string, are:

refs=comma-separated list of reference IDs
This is the desired list of reference IDs separated by commas (with no spaces).
callback=name of the callback function
By default the service returns JSON data, which is great but not convenient for browsers that do not support CORS yet. For those, simply adding the callback parameter with the name of the callback function you want will switch the response to JSON-P.

Some examples should help:

// get references for SVG, REX, and DAHUT
GET http://webref.herokuapp.com/bibrefs?refs=SVG,REX,DAHUT
// the same as JSON-P
GET http://webref.herokuapp.com/bibrefs?refs=SVG,REX,DAHUT&callback=yourFunctionName
// get cross-references for the CSS Object Model and File API specifications
GET http://webref.herokuapp.com/xrefs?refs=cssom,fileapi
// the same as JSON-P
GET http://webref.herokuapp.com/xrefs?refs=cssom,fileapi&callback=yourFunctionName
        

If you need to find a reference ID (for either bibliographic or cross-references) you need to either lift it from an existing specification, or to find it in the source database. Where to get the latter is explained below. Please note that the identifiers for bibliographic references are not the same as for definition cross-references, and that just because a specification is featured in one does not mean it is also in the other. (Historically, those were two separate databased that were merged. Or, if you really insist on accuracy, the CSS bibref DB was converted into the ReSpec JS DB; the latter was extensively extended and edited, forked into the Specifiction database which was edited, then into the ReSpec v3 database which was also edited, then much of those were merged; in a parallel universe the Anolis bibliographical and cross-reference databases were developed; then all of these were merged into this service. So stop whining and delight in the consistency that you do have.)

Format

Both APIs return JSON Objects that have one key per requested reference ID. If a reference ID was requested but not found, it will be present in the results but point to an empty string. The values for those keys are then different depending on the reference types.

For bibliographical references they are:

html
This is a serialised HTML representation of the reference. It is being phased out, and while many references still feature it a lot of them don't and that number is expected to grow. Only rely on it when it is the only option. When editing the database, only create html entries if you need a reference that cannot be adequately described by the other fields. When the html field appears, all the other fields are forbidden.
title
The title of the specification. This is the only required field.
href
A link to the specification. Please note that by convention, unless you are deliberately creating a dated entry (as explained in the next section) this should be a link to the latest and greatest version of this specification.
authors
An array of strings being author/editor names.
publisher
The organisation in charge of publishing the document. This can be anything, but it will typically be "IETF" or "W3C".

The format for definition cross-references is:

definitions
An object the keys of which are the defined terms and the values of which are the IDs used to reference those definitions in the document.
url
The URL to the document from which those definitions are extracted and to which they should be linked. Note that the expectation is that a processor can take any ID from the values in definitions and just append it to url, which means that you should include the # at the end of the URL.

Updating & Adding

You can make modifications to the databases simply by editing either bibrefs.json or xrefs.json in the GitHub repository at https://github.com/darobin/webref/, using the format described in the previous section.

In order to do so you can fork the project and make a pull request to update it, or you can ask to be added as a project collaborator (we're pretty open about that) in which case you'll be able to push changes directly (if you promise to be careful about conflicts and double-checking your JSON syntax).

Whenever a change is pushed to that repository it automatically gets synchronised to the service's database within a few seconds.

Some rules to observe when editing the databases follow.

For both DBs:

For the cross-references DB:

For the bibliographical references DB: