Describing REST APIs with HTML5 forms


There are several options for describing APIs in a way that machines and/or people can read: WSDL files (mostly used with SOAP), OpenSearch description files, YQL Open Data Tables, etc.

I had a theory that REST APIs could be sufficiently described — in a way that both machines and people can understand — using HTML5 forms.

Here's an example, describing the NCBI's ESearch API (part of EUtils):

This makes use of several new or modified HTML5 attributes on input and select elements: "type", "required", "pattern", "placeholder" and "autofocus".

The description needs to be able to define:

  • which fields are available ("name")
  • their default values ("selected")
  • whether values are required ("required")
  • hints for when required fields are not filled ("title")
  • what type of data is in each field ("type")
  • patterns to validate the data in each field ("pattern")
  • possible options for each field, when the set of options is limited ("select/option")
  • human-readable descriptions of each field ("label")
  • suggested values or hints for the formatting of fields ("placeholder")
  • dependencies between different fields ("optgroup", "class")

Still needed: a way to express dependencies between fields (e.g. "either this or these are required").

Deliberately missing: any definition of the structure or semantics of the response.

Here's another example, for EFetch. This one is missing optgroup elements, while I investigate the different combinations of parameters.