Self-documenting APIs

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.

Costs to Expect API

The Costs to Expect API is ready for release*.

I’m going to continue development to add additional features and start working on the summary endpoints and endpoints required for the companion website, however, the API itself could be released today.

The API is ready, five years and two months of child costs exist, the two need to be put together.

I’m going to work with my Wife to review and categorise the data. Our data is categorised, however, for the API we want to break the data down a little more, our data is split into thirteen categories, we intend to have fewer base categories and subcategories to provide the detail.

*I’m not setting a release date, it will be soon though, I want to get the API out before I look for a new contract and go back to work.

Once the API is out, I will start development on the companion website for data input (preview for iOS app), the iOS app and the website to display the data.

We have several long-term plans for the Costs to Expect API and website, one being to allow additional data, for example, localised costs for childcare/hobbies etc. Our intention is you will be able to augment our base data to get a more accurate idea.