How not to develop an API

An API built to expose data to 3rd party applications should act as a clear, simple and accessible window into the source application’s world.

I recently worked on a single-page restaurant booking application that allows users to check the availability of a table for a specified number of people at a specified time, and from this experience I took away a few key points that I will endeavor to abide by when building my own APIs in the future, and which I hope will also come in handy for anyone researching API development.

I’ll start with the obvious, then I’ll move on to have a small rant about my experience with a certain vendor that shall remain nameless.

Data should be described in one language

Every nation is proud of their language, and that’s understandable, but if you really want to write an API using non-English, then you should be consistent. Having method calls and constants in English, keys in the JSON in a mixture of English and French, and user-facing text in Spanish leads, only to confusion and an increased dev overhead.

We work in a world where English is the dominant language in programming so, until that changes, keep your constructs in English: methods, keys and constants.

Here is also a good time to mention the use of a spell-checker.  It’s not only frustrating and embarrassing to have spelling errors in a public facing API: it’s worrying.

Every company has a reputation to uphold, and if a programmer makes mistakes in the public areas of the code, what about the internals?


Any internationalized data should be scoped by a locale string. This can be part of the request. For example:


Or, if the client system needs to deal with multiple languages simultaneously, it can be a part of the response:

The API should be thoroughly documented

This is a given, I know.

I’m guilty of being lax when it comes to documenting my own code. A lot of the time I assume that just because it seems obvious to me, it should be obvious to everyone else. Often times methods are self-documenting; well-written, or simple enough, that it’s not necessary to add description.

But when it comes to APIs, assume the developer knows nothing. Because that’s what I know: Nothing. I’m not familiar with your definition of ‘slice’, ‘slot’ or (and here we go back to the language confusion question) ‘traduce’, and I certainly don’t know how the returned data is formatted without a guide.

Developers aren’t always online; Servers aren’t always reachable

At first glance it appears to give you all you need to make a request and process the received data: parameter description and an example of the response. Assuming the vendor has provided a development server to test against, I can make my request and retrieve the data, filling in any blanks in my understanding of how the data is structured.

Now assume that the development server is down for maintenance, or that the dev server is limited to one user (this actually happened), and that you’ll have to wait for at least a couple of weeks before they can provide you with access because another team is using the system. What now?

Figure 1: API documentation for get_opened_lunch_list
Figure 1: API documentation for reservation_get_opened_lunch_list

I had scheduled time to work on the project only to find that I couldn’t access their system. I couldn’t work against their server, and I couldn’t work against stubbed data because I had no idea what was being returned. I had to wait, there was no other way.

This, by the way, is what was actually returned:


Support your developers

The chain of back-and-forth emails between the development team, the direct client, and the API vendor was seemingly never ending. Luckily, my colleague dealt directly with everyone, saving me from pulling out what’s left of my hair.

The buck was constantly passed between the client and the vendor. We would ask for direction, assistance and clarification on various aspects of the API, only to be left waiting days for a reply. Even then, the reply would inevitably gloss over the finer details, leave some out altogether, and occasionally fail to answer all of our questions.

Lack of technical support, incomplete documentation and a repeated shortage of development servers, resulted in huge delays to the project. In all, this 3 day project was finally finished after 9 months. My son was literally conceived and born during the time it took to finish this ‘short-term’ project.