Some tips for building an API

Our company has accumulated good experience in creating various APIs. Some of this experience has been gained through bumping. We want to share with you some tips that we ourselves are trying to follow to make it easier for you to develop and maintain your own product in the future.

Versioning

From the very beginning of the development of your API, no matter how small it may seem to you, include in the architecture the ability to version your API. If you don’t want to write code to support versioning right away, then at least agree on how you will do it in the future. At the very least, you need to be prepared for this.

Determine the support period for legacy versions

It is also advisable to agree in advance at the design stage how long you will maintain the old versions of the API, how many versions are considered active, who decides that this or that version is now considered obsolete.

Remember old customers

Always remember that your API may be used by old clients who do not know anything that you may have changed something in your methods. This is especially true when creating APIs for mobile clients. If you change any logic of the methods, it is better to do this by creating a new version of this method than changing the current one. It is only permissible to change the current method if it does not affect the incoming and outgoing parameters. That is, if you change not the method itself, but some logic deep inside the code.

Observe uniformity in the names of methods, parameters

Agree in advance about how you will name the API methods, incoming parameters, etc. You may not follow any generally accepted standards. The main thing is that there is no different naming logic inside your system.

Bad example

GET https://api.example.com/product/list – API method for getting a list of products GET https://api.example.com/offers – API method for getting product offers. As you can see from the example, in one case the list is requested by url where the object is named in the singular, and then the word list follows, and in the second example the object is simply named in the plural. In general, both methods are immediately understandable, but in this case it would be correct to use everywhere either the plural or / list

Good example

GET https://api.example.org/products GET https://api.example.org/offers

Use the same names for incoming parameters

Developers using your API will find it much easier if you maintain consistency in the naming of your API parameters. This applies to parameters that filter the results in some way or, for example, specify the sort order.

Agree on basic structures that may be in the answers

Agree right away on what basic response formats your API will have, and then strictly follow these conventions. Usually, in all APIs, requests can be divided into three types:

  1. Obtaining information about a specific object

  2. Getting information about several objects of the same type (list)

  3. Performing any action on an object or objects. So, your API should be implemented in such a way that each method assigned to one of the three listed groups returns in a similar structure.

For example, methods from the first group can always return data in the following structure:

{
    "result": <object>
}

The list can be returned like this:

{
    "items": [
        <object>,
        <object>,
        ...
    ],
    "count": (int),
    "limit": (int),
    "offset": (int)
}

And the API method of action on an object or objects can return either a 200 code with an empty body, or, for example, a modified object (as in the first example).

Accept a uniform error return format

This point could have been included in the previous one, but it seems so important to us that we decided to describe it separately. Design your API so that all methods return errors in the same style and format. It will be very bad if some methods return the 400 Bad request http code with an empty body, while other methods return, for example, 200 OK and the response body will contain information about the error.

Make it convenient to display a list of objects

Pay attention to the example of returning the list from the previous paragraph. There, in addition to the list itself, auxiliary information is also returned about how many objects were found for this request, how many objects were requested and what was the indent from the first result. This way of serving a list can greatly simplify the lives of developers who will be working with your API. They will always be able to build “list loading” or “page navigation”.

The method indicated in the example is not the only correct one. You can also use, for example, the has parameternextpage signifying whether it makes sense to execute the next request. The main thing is that developers using your API do not have to make an extra request to get the list.

Write documentation

Yes, it’s no secret that no one likes to write documentation. But you must write it.

Documentation can be divided into two types

  1. Internal documentation. It is desirable to describe all the conventions in it: codestyle, naming conventions for methods, parameters, response and request formats, etc. This kind of documentation, at a minimum, will help new developers get into the work faster.

  2. “Public Documentation”. Even if a neighboring department will use your API, you still need to describe your API. Here you need to describe the response formats, how to properly handle errors, etc. It will be great if you have documentation on the methods of your API. It’s good if for each method you specify:

  3. Request example

  4. A short description of what happens in this method

  5. Description of incoming parameters (type, name, required or not, brief description if needed)

  6. Sample response

  7. Description of each field in the response (name, type, description). You can either write such documentation “by hand” or use various software to help solve this problem (for example, swagger). It is imperative to keep your documentation up to date at all times. It is better to monitor this constantly, since then it will be very difficult to bring it to its proper form.

Predictability of actions

Design API methods in such a way that they are as clear as possible, even from their own URL. Method names should be as descriptive as possible. For example, a method that returns information about a user should not modify it. Of course, there may be exceptions to any system and any rule. But then it should be explicitly stated in the documentation.

Unified format for authorization and transmission of authorization data Within one API service, you must have a unified format for transmission of authorization data.

Tests

Write tests. This helps a lot not to break what is already in production. Even if there is no time. Force yourself and you will end up saving a lot of time in the future. Conclusion You may have noticed that almost all of our recommendations refer to the preparatory phase. And this suggests that before developing anything, it is necessary to devote time to designing, preparing a “bridgehead”, so to speak. This will save you development time in the future. It will also help API users to integrate it.

Ask us questions and share your tips in the comments.

Similar Posts

Leave a Reply