- Context
- Research
- Which API specification approach should we use?
- How would a developer validate its API usage against the specification?
- How do we ensure that API specification and implementation are in sync?
- How to generate the specification
- How to visualise specification
- What does the documentation include?
- How to host documentation for current
master
HEAD - How to document extension link relation types?
- Client-side validation
Note
|
Author: Lucas Soriano del Pino <[email protected]> Date: 2019-08-29 Tracking issue: #1122 |
We have no documentation for cnd’s HTTP API. Having it is a hard requirement if we want to cater to application developers. It should also be helpful for the team and for newcomers.
-
Extremely popular (specification has over 15k stars on GitHub).
-
APIs can be specified using either YAML or JSON.
-
"Winner" of API Description Wars.
-
Quite popular (specification has over 3k stars on GitHub).
-
APIs can be specified using YAML.
-
Good for designing large numbers of APIs.
-
Company behind joined Open API Initiative in 2017.
-
Very popular (specification has over 7k stars on GitHub).
-
More accessible to newcomers to API description.
-
Targets human readability over machine readability.
-
APIs can be specified using a description language on top of Markdown (conforms to GitHub Flavored Markdown).
-
Company behind joined Open API Initiative in 2016.
-
More flexible.
-
No tooling.
-
An example showing how it could look.
OpenAPI, because it appears to be the industry standard, and is compatible with the most tools. The better human readability of API Blueprint doesn’t seem all that important given that these specifications can be viewed using powerful tools such as ReDoc.
-
Online tool.
-
Quick, manual testing.
-
Can generate OpenAPI specifications from requests and responses.
-
Language-agnostic.
-
Works with both OpenAPI and API Blueprint.
-
Very popular (over 3k stars on GitHub).
-
Command line tool.
-
Takes API specification and makes requests to server based on that, reporting whether the responses match the documentation.
-
Example:
dredd cnd-http-api-description.yml https://localhost:<port-where-cnd-is-hosted>
-
Can run code before/after specific tests by using hooks (Rust and JS are supported).
-
Easy integration with test suite by using a config file.
-
CLI can help modify CircleCI config for continuous integration.
-
Uses examples in specification to generate expected responses.
-
Can define custom expectations using Chai assertions.
-
Works with Chai (which is compatible with Jest).
-
Easy to incorporate to our api tests workflow.
-
Example from GitHub repository:
// Set up Chai const chai = require('chai'); const expect = chai.expect; // Import this plugin const chaiResponseValidator = require('chai-openapi-response-validator'); // Load an OpenAPI file (YAML or JSON) into this plugin chai.use(chaiResponseValidator('path/to/openapi.yml')); // Write your test (e.g. using Mocha) describe('GET /example/request', function() { it('should satisfy OpenAPI spec', async function() { // Get an HTTP response using chai-http chai.use(require('chai-http')); const app = require('path/to/app'); const res = chai.request(app).get('/example/request'); expect(res.status).to.equal(200); // Assert that the HTTP response satisfies the OpenAPI spec expect(res).to.satisfyApiSpec; }); });
Dredd, because it’s well documented and has all the features we need. It looks like the main effort will be preparing the specification for testing.
We currently use JSON Schema to validate the shape of the body of the response to GET /
swaps
and GET /
swaps/rfc003/:id
.
JSON Schema is supported by OpenAPI, with some caveats.
There are ways to get around this situation, and full support for JSON Schema is in the works.
-
Switch to actix-web and use this experimental plugin.
-
Wait for Rocket to implement this feature and switch back to it.
-
Wait for this feature to come to warp.
-
Use Swagger Editor (over 5k stars on GitHub).
-
Use a plugin for an editor/IDE (look at the editors listed here).
-
Using Swagger Inspector.
-
Make API calls to a running cnd through the UI and generate part of the specification.
The tools aren’t there yet to automatically produce the API specification from source code in Rust. There seems to be some interest for this, so it may come in the future. This may not actually be a problem, since we want to have control over what we show in the specification, in order to incentivise correct usage of the REST API by application developers. To this end, endpoints such as the ones related to actions will probably not be publicly documented.
-
Include API specification in repository with cnd.
-
Host a website on GitHub Pages (for example).
-
Use a HTML tag that links to the API specification (there’s even a React component).
I would argue that this is covered in the original issue.
Just replace human-protocol-spec
key with a link to a static HTML page hosted on GitHub Pages (for example) where the meaning of human-protocol-spec
is described.
-
We already define JSON Schemas for some data objects returned from the API.
-
We have discussed doing input validation on comit-i.
-
We currently reproduce server-side validation on comit-i.
-
Define JSON Schemas for all data objects that our API returns.
-
Offer a copy of these contracts to clients in a programmatically accessible format.
-
Include link to in response header:
Link: <https://example.com/schemas/swap.schema.json#>; rel=”describedby”
-
Use in comit-i to prove that it works.