Designing and documenting your API

API’s are a wonderful thing. They can allow other developers to use data or features of your application and even use it in a way you didn’t foresee beforehand.

The hard thing is not writing the API (because hey,.. we all got them skillzz right?), but coming up with an easy to use and scale-able design. The interface needs to be appealing to developers and having a different design every release will completely destroy the entire reason on why you created interface in the first place.


Create a new layer, do not just provide an easy way to access the first one

Your application should consist out of two different layers. One being the objects you use in your main application. The API layer should have its own objects and interfaces to ‘get’ those layer#1 objects.

One of the most commonly reasons for programmers to change their API is because they decide their first layer isn’t abstract enough and rename/refactor all objects. This breaks the API and will cause 3rd party developers to implement it again (or,… get angry… usually both).

Having that 2nd layer will allow you to do the ‘translating’ from your old ideology to your new one in the background without breaking your existing interface.

Changing your API completely at some point is an imminent truth

Regardless on how abstract and scale-able your API layer is, you will at some point want to change it completely.

One of the most common reasons for changes such as this are ‘knowledge’. You know a shiny new thing that will make things faster, cleaner and easier to understand. Those things sound appealing right?, but do your 3rd party users agree with this?

First ask yourself if those changes really require you to break the API. If that is the case you will have to come up with some way to keep the old version usable for older applications.

Some tips for doing this is adding versioning for your API and deprecating older versions or functions.

You will see a lot of REST API’s with http://api.myapp.com/v1/….
Or software API’s where the versioning is done in the interface layer that is provided in separate binary.

You could even create a completly new layer for the new API and use your old API to “access” the new API.

Create a story

I am not talking about use cases here, but its getting close. Create a story on the flow a developer would use your API. Usually everything is connected so that also means your design needs to adapt to this flow.

For example: You have an application to get the sports results.
Notice that I didn’t specify what sports, what teams ,… because the developer using your API doesn’t know that either. You will have to provide a flow on how to find that information either by documenting it or providing a way to get it.

GET http://api.mysportsapp.com/v1/sports
.. rugby, … hockey
GET http://api.mysportsapp.com/v1/teams/rugby
.. Team1,Team2,…
GET http://api.mysportsapp.com/v1/games/rugby/team1
.. Game1,…
GET http://api.mysportsapp.com/v1/games/game1
1–0

The above is a little ‘exaggerated’ example of a story. Even without knowing the documentation or the application, you could guess how and what it does just by looking at the design.

Documenting an API is cool, maintaining it is boring

If you are like me, you won’t mind creating that initial documentation for your API (aka. first page). But it’s the maintaining of that documentation that gets me every time and sits on the shelf for weeks until you get tired of people asking you about ‘those new features’.

Well, obviously the best practice here is to just not let it stack up. But yeah, … ain’t nobody got time for that. A good way to keep your API documentation up-to-date is to use inline documentation such as JDOCS in Java or creating your documentation before your actual implementation. That last one is probably the best you can do because you can instantly see the pros and cons in your design.

Define what you can or can not do

A lot of documentations lack the ‘rules’ of what you can or can not do with the API. Can I use it multi threaded? Can I make 100 req/s?

While some of these questions may seem ‘normal’ to you , they may not be normal for someone who doesn’t know the internals. Providing information of the origin of data is very important in particular.


So if there is one thing you should remember when creating an API for your application, web app or whatever future technology that may need to be accessed by other developers. It is that you should consider the fact that how good and great your design may be, it can still be better — and once you realize that you have to make sure that you don’t just click the “delete” button and start over.