In computer programming, an application programming interface (API) is a set of subroutine definitions, protocols, and tools for building application software. So here’s a small effort to make the API term familiar to you. Just as a graphical user interface makes it easier for people to use programs, application programming interfaces make it easier for developers to use certain technologies in building applications.

Good API is boring without exceptions
There is no need to invent anything new in an API. In other words, a new one should be more similar to an existing one. The system behavior should be same in everywhere and at every stage. It works for both the principles of API endpoint construction and input/output data formats. User needs boring, standard API error messages and request/response headers. Fields with every data type should always have the same output and input formats. All empty fields should look the same.

Programming your API process is not an invention; the more you have built up around it, the much you (and your clients) have to disentangle later. In other words, the more boring you design an API, the more satisfied your clients will be with it.


API documentation describes what services an API offers and how to use those services, aiming to cover everything a client would need to know for practical purposes. While nobody ever seems to have enough time for these things, it is the face of your API. It might be worth to put off your much more interesting API coding challenge to invest in writing this documentation. Here are some basic tips for doing it well:

Always offer working examples of HTTP requests and responses or of actual working code.
Documentation should be formatted as consistently as the API itself.
The foundational principles of your API should be described clearly and in detail.
Use API frameworks such as Swagger, Apiary or Postman.

Errors handling

Even if API has poor documentation, it is possible to get quite far relying only on error messages, if they are good. As a rule, accurate and clear error messages really matter to the user experience. Even for API developers, good error messages make you more confident in your work and help you react to errors quickly.


Every authorization type is useful if it’s STANDARDIZED. So it’s very important part of the process. Working on authorization processes becomes a real issue if it’s unique in some way or is too weak. For example, OAuth is an API that generated a refresh-token on every access-token update, and also needed access token expiry time. It’s bit a hard process. First, let your users decide what security level they need and if you can allow non-expiring tokens. Second, keep the processes uncomplicated. Many good APIs use static refresh tokens.

Data formats

Thinking about constructing new data formats like custom data formats is useless. Parsing of unique data format slows work down a lot and makes it a chore to do. It is hard to suppress your creativity when it spills out into these strange ideas. Some innovative ideas are difficult to throw purely because of your own parental feeling towards your creation, but you must resist because we already have JSON and XML.

The advantages of using specifications like JSON API are wonderful. Stripe, Braintree and lots of other companies are already using it successfully because JSON has an easy to use structured data format. Support multiple data formats are not good in APIs. Customers do not generally care which standard data format they use because all programming languages and technologies already support data formatting and parsing for every standard type. Including multiple formats only slows your API and documentation maintenance down.

It is very confusing for a developer to get inner API errors with HTTP status 200. This really slows down development. And HTTP status codes can fill the error message role in many cases. Common examples include in here and more on Wikipedia.


Without any special reason to change it, your content type always should be the same. It helps keep client architecture consistent, and accelerates and simplifies the development process. Also avoid allowing several supported content-types for an endpoint. Developers working with that endpoint could be confused by this. For example, your endpoint “A” works fine but endpoint “B” returns a Bad Request error even though you use it in the same way. Changing your content type doesn’t look like an obvious solution.

Object structure

From the client’s side of things, it is always very helpful to know what actually the entity fields have. That is perfect if API has a special endpoint that returns a full entity field map. Otherwise, you should at least ensure that you object/list get returns every field even if it is empty.


For an instance, an API connector in a famous CRM system, that it has NO pagination records. When searching the technical support about this, it seemed unbelievable. So what pagination is perfect:

· It’s useful when you can control pagination page size. It enables users to choose for themselves between quantity and quality of requests.

· It has Meta information to understand how many records summaries we have. In a case of loading all the records, it really helps to understand progress. Also, records counting doesn’t require loading of every page, let’s not waste time and money.

· The clear and constant naming of pagination variables, for example: page_number — current page number; page_size — pagination step size; pages_total_count — total count of pages.

Images and files

Obviously we shouldn’t include files or image bodies inside responded data. It is much better if you return a temporary upload link.

Time and date

It is really important to explicitly specify what time zone we use. It could be part of the time format or just a phrase in the documentation. How to use time zones deserves a separate article of its own. You can just return date in integer numbers of seconds since the UNIX converted it into a UTC time zone. Every client can handle this to correct their format and time zone.

Payment plan

You should use HTTP status codes to inform a client when they try to use payment-required endpoints on a free or “not enough paid” plan. Sometimes it is rather difficult to understand what went wrong, and it wastes time to keep fighting with nothing while trying to choose the correct request format. Using the 402 payment required HTTP status code here. You can pick any other code you want but it should be clear what is happening. API documentation should have notes about these using conditions as well.

API limits

If programmatically limit request counts in an API, when it reached the limit and want to see a clear error message. Ideally, there would be a special endpoint with this information. It’s a good idea to render information about available API calls in HTTP Response Headers. Examples of API Limits are in ZohoCRM.

For example:

Logical aspect

While developing an API, lots of helpful things at an early stage. In some APIs that when deleting a record twice, you’ll get the same response each time. This is bad because it allows your client to incorrectly believe that they removed it again or removed a different record already. It should return a 404 HTTP status code if the record was already deleted, to help your clients to notice their mistakes.

Another observation about APIs

If you have strange API endpoints it may be a sign of something really bad in your project design. So instead of creating facades and adapters, take good opportunity for a refactoring iteration that both will simplifying your API interface and improving your project structure.

By Janani Bodaragama