During my professional career I’ve worked on many APIs, however, I’ve never been responsible for the entire design, development, and support of a large API. When creating the Costs to Expect API I wanted to ‘as good of a job’ as I could.
Over the years I’ve heard the term self-documenting APIs but had never really looking into it. Regardless of the agreed definition, I’m going to describe what it means to me. Hey, this is the internet, we all have opinions.
To me, there are five points.
- The initial entry route or an obviously named route should display all the endpoints.
- The initial entry route or an obviously named route should show the current version of the API as well as provide links to the README, CHANGELOG and anything else useful.
- There should be a changelog route to describe all changes and updates to the API.
- An OPTIONS request should exist for every route. The OPTIONS request should detail the purpose of the route, all verbs, as well as any fields and parameters.
- No redundant information in either the payload or the response, for example, the payload should not be wrapped in an envelope, the verb is the envelope.
As a bonus, API versioning should be controlled via the route, any payloads or responses should be free of any version information.