All Open Data APIs Should Have Machine Readable Metadata, Says ODI ...And Here's How

The UK’s Open Data Institute is encouraging all API developers to include a machine-readable metadata description whenever publishing an API that enables access to a dataset. The proposed publisher guide defines best practice in how to include a machine readable rights statement in API Documentation, and follows recent international efforts to define API standards and best practices.

The Open Data Institute (ODI) is an independent, non-profit foundation aiming to be a catalyst bringing about a widespread open data culture. It is currently funded by the UK Government and the philanthropic Omidyar Network (created by eBay founder, Pierre Omidyar).

The ODI’s Open Data Rights Statement argues that:

"Data published to the web should always be accompanied by machine-readable metadata that describes the dataset, its means of creation and, importantly, a statement of the rights that relate to potential re-use of the data."

The ODI’s Publisher Guide explains this further:

For example a statement of rights may typically include some or all of the following information:

  • A reference to a Dataset Licence
  • A reference to a Content Licence (if, and where applicable)
  • Copyright notices, that should be referenced or displayed by re-users
  • Guidance on a means of attributing the source of the data, e.g. when re-used in an application
  • Pointers to further information, e.g. further guidance on re-use or details on how to acquire additional rights.

To assist API developers, the publisher guide includes a detailed section and Sample Code on how to link to rights statements from web APIs. They argue that when open datasets are published via a Web API it “should also be associated with a clear rights statement”. A link HTTP header can be used to add links to HTTP API responses. A custom link relation can also be added.

Given that many web APIs are based on JSON, the publishing guide gives examples of simple JSON objects, and coding examples for publishing linked data as JSON. The publisher guide was released at the start of July on Github and ODI welcomes feedback.

Be sure to read the next News Services article: Where Do We Lead the APIs of Tomorrow? API Craft Aims to Find Out