Best Practices: API Design

Well designed APIs = Happy Developers 😃

Application Programming Interfaces (APIs) are interfaces that make it easy for applications to use data & resources of another application. They are vital to the success of a product or company.

Without APIs, most of your favorite software wouldn’t exist today. For example, the Google Maps API lets you use Google Maps in your mobile or web application. Without it, you would have to design & develop your own maps database! Imagine the time it would take to display a location on the map if there was no API.

Why should we use APIs?

1. APIs enable outside access to your resources
2. APIs extend the capabilities of your app
3. APIs allow developers to reuse application logic
4. APIs are platform-independent, they deliver data without being affected by the requesting platform.

In most real-life scenarios, a data model will already be in place, but since we’re going to discuss the best practices for API design, we will start from scratch.

Data-Modelling & Structuring

Modeling your data with the API in mind is the first step in designing easy to create, maintain & update your APIs.

When designing an API, always consider using terms that are generic, rather than using complex business terminology which may not be known outside of your organization. Your APIs may be used internally or you may plan to expose your API to allow external app developers to use your API to develop their apps. By using generic terms, you make sure that the developer using your API understands your API & can quickly get up-to-speed with the integration.

Consider that you are building a portal that lets users review books from various writers. Your organization may use company-specific terms such as Storytellers, creations, series, etc for Authors, books & series that they create. But for simplicity & to allow external app developers to use your APIs, you would create API paths by using the generic concepts over company-specific terms.

https://api.domain.com/authors
https://api.domain.com/authors/{id}/books

This helps understand new developers to quickly understand what your API is about and how to traverse your data model.

Writing resource-oriented APIs

Apps that use your APIs are looking to access your resources. Maintaining a resource hierarchy helps you structure your APIs better. A resource hierarchy is each node in your path that consists of a collection or a resource.

The resource can be a single piece of data, for example, the profile of the author from the above example.

The collection is a collection of resources, which in our case could mean the list of books written by an author.

Here, your resource hierarchy can be:

Base Path -> Authors (collection) -> profile (resource)
Base Path -> Authors (collection) -> books (collection) -> book (resource)

You want to be consistent with your hierarchy to make sure developers encounter minimum questions while connecting their application with your API.

To maintain simplicity & consistency, here are some guidelines that will help:

1. Use American English while naming your collections & resources. (Example: color over colour)
2. Avoid spelling mistakes
3. Use simpler, commonly used words to maintain clarity, such as delete over remove.
4. If you’re using the same resources which are being used by another API, use the same terminology to remain consistent.
5. Use the plural form for collections (example: authors, books, etc)

Be RESTful

The most widely accepted standard for sending HTTP requests to an API is REST — Representational State Transfer. It basically means that each URL represents an object.

The purpose of the API can be one of the following:

1. Create data
2. Read data
3. Update data
4. Delete data

CRUD! Yes, you guessed that right!

These purposes of an API are handled by using a set of HTTP verbs that define the nature of the request & what it should do.

The GET verb is associated with retrieving data from an API. It asks for a representation of the data from the API. A GET request can include query parameters to filter the result you receive from an API.

The POST verb is associated with submitting an entry to the API which will create a resource in the database.

The PUT verb is generally used to update an existing resource on the server.

The DELETE verb, well as the same suggests, deletes a resource from the server.

Here are some examples of using HTTP verbs & their description:

API Versioning

The longer the application’s and API’s lifespan, the greater the commitment to the users of the application and API. At some point in time, your API is going to require changes since you cannot foresee changes that will occur with changing requirements and business policies.

So, it may be required that you make changes to your API. But your API may already be in use by one or more developers, so it is important that you make changes in a way that does not break your partner developer’s application.

Understanding major & minor updates

Minor version upgrades can be used when you are not making changes that would break your client’s application, such as adding optional fields or support for additional parameters. This is the time you can increment the minor version for your APIs.

Major version upgrades are the ones that will most definitely break your client’s application such as adding a new required parameter in the request payload or changing the fields in the response.

There are a number of ways you can version your APIs.

The most common way is to include your version in the URI.

https://api.domain.com/v1.0/authors

The next way is to use date-based versioning. This includes the date on which your version was released to the URI. The benefit being app developers can understand how frequently you make changes to your API.

https://api.domain.com/2020-06-15/authors

Another way is to include the API version in the headers.

https://api.domain.com/authors
x-api-version: v1

The most recommended & accepted way of versioning is using the version name in your URI.

Pagination

In the world of increasing data points, it is impossible to show all the data on a single screen at the same time. That is why it is important that you let your users fetch a certain number of documents before requesting for data again. This is called pagination and the data set returned is called a page.

It is recommended that you use specific phrases in your request and response payloads to enable pagination in your API. These are:

1. STRING page_token (sent in the request)
2. STRING next_page_token (returned by the API)
3. INT page_size (sent in the request)

The page_token request which page does the API needs to return. This is usually a string. For the first API call, page_token = “1”

The page_size defines how many records should be returned in the response. For example page_size = 100 will return at the most 100 records in an API call.

The next_page_token defines what is the next token in the series. If after the page_token="1" there is additional data, the value returned is next_page_token=”2”

If there is no more data available and the user has reached the end of data, a blank value is returned next_page_token=”” .

There you go! These are the best practices when designing your APIs to be robust, concise & easy to integrate with other apps.

Remember:

Well designed APIs = Happy Developers 😃

APIs are like bridges, they connect two services with one another. Photo by Joseph Barrientos on Unsplash