8 Tips for Building an API

At Twelve Data, we have a lot of experience in creating various APIs. Some of these tips have been gained through practical errors. We would like to share with you some of them that we ourselves are following in order to make it easier to develop and maintain our 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, take versioning into an account in your architecture. If you don't want to write code to support versioning right away, then at least try to 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 at the same time are considered active, who decides that version is now considered obsolete.

Think About Original Users

Always remember that your API may be used by original clients who do not know that you have changed something in your newest endpoints. This is especially true when creating APIs for mobile clients. If you change any logic inside the endpoint, it is better to do this by creating a new version of this endpoint than changing the current one. Changing the existing endpoint is only valid if it does not affect the incoming and outgoing parameters. 

Maintain the Same Style in Paths and Parameters

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

Bad Example

x

GET https://api.example.com/product/list - get list of products

GET https://api.example.com/promotions - get list of promotions

As you can see from the example, in one case we request the list by URL, where the object is named in the singular form, followed by the word list, and in the second example the object is simply named in the plural. In general, both the first and the second methods are immediately understandable, but in this case, it would be correct to use everywhere either the plural or /list format.

Good Example

xxxxxxxxxx

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

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

Use the Same Names for Input 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. 

Define an Error Response Structure

Design your API so that all methods return errors in the same style and format. It will be very inconvenient if some methods return a 400 Bad request HTTP code with an empty body, while other methods return, for example, 200 OK, and the response body contains information about the error. 

Create Stunning 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: code style, naming conventions for methods, parameters, response and request formats, etc. This kind of documentation, at the very least, will help new developers get started faster. 
2. Public documentation. Even if a neighboring department will use your API, it still needs to be described. Here you need to describe the response formats, how to properly handle errors, etc. It will be great if you have documentation of the methods of your API. 

It's good if for each endpoint you specify: 

• Sample request;
• A brief description of what happens in this endpoint;
• Description of input parameters (type, name, required or not);
• Sample response;
• 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, such as 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.

See the good documentation example in Twelve Data

Tests

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 design. This will save you development time in the future. It will also help API users to integrate it faster.