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):
- HTML5 form
- YQL Open Data Table, for comparison
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.