During my professional career I’ve worked on many APIs, however, I’ve never been responsible for the design, development and support of an API of more than trivial scale, when designing my own I wanted to do ‘as good of a job’ as I possibly can.
I’ve heard the term self-documenting APIs and never really looked into it, regardless, I’m going to describe what it means to me, hey, it 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 possible 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.