Agencies should list private, internal, and public-facing web APIs as part of their Enterprise Data Inventory and Public Data Listing data.json files. The original v1.0 schema accommodated the listing of APIs with a separate webServices
field, but with the v1.1 schema, APIs should now be listed as a separate distribution within a dataset. Since an API provides indirect access to a dataset and the primary URL that a user needs in order to access the API is the API documentation, all web APIs should be referenced using the primary API documentation URL as an accessURL
with the format
specified as “API”. The downloadURL
and mediaType
fields should be left empty for a distribution that describes an API, but if the raw data download that powers the API is also available (as it should be) then that should be specified using the downloadURL
and mediaType
of another distribution entry on the same dataset.
For APIs that also have machine readable documentation (like Swagger, RAML, API Blueprint, HAL, Hydra, etc) it can be specified with describedBy
and describedByType
. The URL for the machine readable documentation should be specified by describedBy
and describedByType
should be a media type that identifies the format of the machine readable documentation.
These media types should be used for the describedByType
field along with the URL to the machine readable documentation itself using the describedBy
field. This should not be confused with the format
field which should be “API” for an API and mediaType
which should be blank for an API.
application/swagger+json
application/raml+yaml
application/vnd.apiblueprint.ast
in abstract syntax tree form, plus others depending on the serializationapplication/hal+json
and application/hal+xml
for the JSON and XML variants.application/ld+json
with rel="http://www.w3.org/ns/hydra/core#apiDocumentation"
included in the Link
HTTP header. Some APIs may implement a common standard such as WMS, WFS, or Open311. If this is an established standard, use the canonical URI for the standard as the value for the conformsTo
field in the same distribution object where the API is listed.
"distribution":
{
"accessURL": "http://www.agency.gov/api/vegetables/",
"description": "A fully queryable REST API with JSON and XML output",
"describedBy": "http: //www.agency.gov/api/vegetables/swagger.json",
"describedByType": "application/swagger+json",
"format": "API",
"title": "Vegetables REST API"
}
]