Over the years I have worked on multiple APIs and created a few myself. Even though I have created several APIs I’ve only solely created one “large” API. Large is down to the reader and your specific experience. APIs which have a dozen or so endpoints can easily be documented in the project README. As soon as you have over 150 endpoints you need a plan, you need real documentation and a self-documenting API.
Definition
What is the definition of a self-documenting API? I have no idea what the official definition of the term is, below I’ve listed my requirements. If I’m way off base here, awesome! Let me know how I’m wrong, you can reach me on Twitter and via email.
Route list
When a developer makes a call to the entry point of your API, the response should document the features. That initial response should include a list of all the routes and the endpoints supported by the API.
We should all read the official documentation for tools we use but as we all know, documentation can easily become stale. If the API lists all the routes and endpoints the user will immediately know where to start looking for what they want.
Version, README and CHANGELOG
In addition to listing the routes and endpoints, the entry point for the API should list the version and include links to the README and CHANGELOG. Bonus points go to the developers who include a changelog endpoint within their API.
OPTIONS
The first two points are nice to have, however, they don’t make an API self-documenting.
Every route should support returning an OPTIONS response. The OPTIONS response needs to provide details (documentation) for the route, The response should list the supported endpoints, the fields and parameters required for each endpoint as well as a general overview of the route.
To see a working example, please make an OPTIONS request to https://api.costs-to-expect.com/v3/resource-types.
The response details the supported endpoints (verbs). The POST section details the fields which can be posted, the data type, validation rules and allowable values for linked data. The GET section details the supported query parameters and the supported sort, filter, and search fields.
Every route of the Costs to Expect API supporting returning an OPTIONS response; they are equally detailed.
Docs?
Yes, the Costs to Expect API still has documention, as great as OPTIONS responses are, you need to provide more detail sometimes. The Costs to Expect API documention lives on Postman and is in the progress of being moved to a GitHub repo.
Regardless of the size/complexity of your API, you need documention.
The longer your API lives the more important the documentation becomes We all forget the specifics after a long enough period, having an API which documents itself pays dividends down the line.