API Design and Documentation

API stands for application programming interface, and REST stands for REpresentational State Transfer. A REST API is a way for two systems to communicate with each other, and it’s the most popular type of API used today.

When building a web service, which is exactly what we are doing, a developer inevitably designs and documents REST APIs at some point. Now mastering the world of API design is tricky and tedious. There is a lot to learn and much of it is passionately debated among enthusiasts frequently. But if we were to dip our toes in and get started with it, where would we even begin? Well, right here, friend!

Key points to consider

Let us go through some of the key considerations to keep in mind while designing REST APIs.

Use HTTP verbs

REST APIs should use HTTP verbs—GET, POST, PUT, DELETE, etc.—to indicate the requested action. For example, GET should be used to retrieve a resource, while POST should be used to create a new resource.

Use nouns

REST APIs should use nouns to represent resources rather than verbs—for example, instead of getCustomers, the API should use customers. This makes the API more intuitive and easier to understand.

Use plural nouns

REST APIs should use plural nouns to represent collections of resources—for example, for a system in charge of storing information about its customer base, instead of saying customer, the API should use customers. This helps to avoid confusion and makes the API more consistent.

Use resource-oriented URLs

The URL structure of a REST API should be based on the resources being manipulated rather than the actions being performed on them—for example, a URL for retrieving a list of users might be /users, while a URL for retrieving a specific user might be /users/{id}.

Use HTTP status codes appropriately

HTTP status codes provide information about the result of a request—for example, a status code of 200 indicates a successful request and is, therefore, the most popular, while a status code of 404 indicates that a resource was not found—you’ve undoubtedly seen this on the internet. Using the correct status codes to communicate a request’s outcome clearly is essential.

Take a look at this summary of status codes below:

• The 200 (and 2xx codes in general) status code implies success of some sort. While 200 is the most generic and commonly used, it is sometimes more appropriate to use a more specific member of the 2xx family, as per our needs.

• 3xx implies a redirect. We came looking for something but are being sent somewhere else.

• 4xx implies an error on the client’s end. One of the most popular lists of codes that have a lot of value in understanding them, we would recommend reading more about 400, 401, 403, and 404 at the very least.

• 5xx implies a server-side error, i.e., we messed up somehow. Here, 500 is mainly used by microservices, while codes like 501, 503, etc., are usually engaged by proxies and DNS servers.

Here’s a slightly deeper dive into some of the popular 4xx codes, which are very common and crucial to be aware of. We don’t need to memorize them all per se but do go through the ones mentioned earlier (400, 401, 403, and 404) at the very least.