Designing Good APIs

Your API is the user interface for your consumers’ developers. It is the first and most important way to access and interact with your product - be it a service or a software component of a reuse library. In other words: your API is your business card.

Many consider API design an art. This would imply that it requires a level of ingenuity and creative spirit to come up with a pleasing result. It would also imply that a good / pleasing API is widely subject to “a matter of taste”. In this article we show that it is actually much more than that.

This is the third blog of a series that deals with the techniques of designing good APIs. In this post we will be focusing on the technique of API First.

Naming is a very important part of designing a good API. Names convey meaning and make using and understanding your API easier. Good naming is half an API’s documentation. So take care about your names.

When designing an API, the aspect of proper error modelling is just as important as error logging, since it will not only allow your consumers to analyse errors, but also to handle them.

A good API focuses only on the business functionality of a service or component and it hides the technical details of the implementation from its consumers.

Even though a good API should be self-descriptive, proper documentation is required. Documentation is not only beneficial for the consumers of your API, but also for you as a developer.