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.

OPTIONS requests

When I published the Costs to Expect API I was initially bemused, none of my OPTIONS requests worked, they all return “405 method not allowed”.

After searching, I diagnosed the problem. The HTTP OPTIONS request fails because the default PHP-CGI handler does not handle the “OPTIONS” verb.

The fix is simple, update or add the handler in web.config.

<handlers>
<remove name=”PHP72_via_FastCGI” />
<add name=”PHP72_via_FastCGI” path=”*.php” verb=”GET,PUT,POST,DELETE,HEAD,OPTIONS” modules=”FastCgiModule” scriptProcessor=”PATH\To\File\php-cgi.exe” resourceType=”Either” requireAccess=”Script” />
</handlers>

Reduced development time :(

As I have mentioned before, I’m lucky enough to be able to take time off during the year to work on my projects, every time I take on a new contract my schedule goes out of whack.

When I’m not contracting, outside of real life commitments, I try to dedicate as many as 30hrs per week to work on my projects, when I’m contracting that isn’t possible, a 40hr week with travel doesn’t leave much free time.

The last two weeks have been an adjustment, I managed to log 5.5hrs the first week and 7.5hrs the second week, I’m on track for 10hrs this week.

Is this a real problem, no, the first world called and wants a tissue, the issue is expectations, during my summer of I steamed through my work, with reality hitting, productivity takes a nosedive. Eventually, Pivotal Tracker will update to show more accurate completion times; once I’m three sprints in, until then, it is frustrating looking at completion dates that are optimistic.

Why am I blogging about this? As the site byline says, I was musing.