api-state-of-play.md

Declarative APIs: State of Play

JSON Schema

• http://json-schema.org/
• Describes/defines a JSON document
• Very popular and well-tooled, lots of validators in many different languages.
• Great for describing/defining/validating JSON responses, request payloads, etc.
• JSON schema is JSON, so human-readability is mediocre.
• Spec is obtuse.
• Tutorial: https://spacetelescope.github.io/understanding-json-schema/

RAML

• RESTful API Modeling Language https://raml.org/
• By mulesoft, has a workgroup with a few familiar companies
• ‘Modelling’ language, as opposed to ‘describing’
• YAML format (nicely human readable)
• Highly composable, with higher-order concepts like resources
• Can use JSON schema to model requests/responses, or RAML type definiton
  • “considerably easier and more succinct than JSON and XML schemas while retaining their flexibility and expressiveness”
• Quite readable spec: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

OpenAPI:

• https://www.openapis.org/ “standardizing on how REST APIs are described”
• Used to be called swagger spec (toolset is still called swagger-ui, editor, etc)
• Broad consortium of supporters (Microsoft, Atlassian, Salesforce, Google, IBM)
• API ‘description’ (instead of ‘model’)
• More tooling than RAML
• Most pundits see API definitions coalescing around this standard
• Mulesoft support it (and are on the working group)
• YAML or JSON
• Much more verbose than RAML, less reusability
• Supports schema that’s painfully close to JSON schema, such that you can just reference JSON schema and it’ll mostly work (unless you’re linting)
• Mulesoft’s pitch is:
  • Use RAML to model cause it’s human friendly
  • Generate an OpenAPI spec because it’s better for tooling to digest
• Also, publish your OpenAPI spec as part of your public API because clients can derive behaviour from it
• Quite readable spec: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md

A definition document like this is only useful if it is

• CORRECT (linted, tested, etc?)
• accessible (easy to read documentation, etc)

Goals to consider for your project:

• Prototyping / design first
• Lint it for correctness
• Drive (some measure of) testing off it
• Drive some measure of implementation off it?
• Drive documentation
• Have a API test harness / client