What does a well structured API look like?

📅 August 31, 2023

💡 API or Application Programming Interface

Is a collection of protocols that allow software components to communicate and share data.

💡 RESTful API or REST API

The most popular API architecture for transferring data over the internet. This architecture, resources are accessible via endpoints using standard HTTP methods like GET, POST, PUT, DELETE

In this blog post, I am going to delve into a well structures RESTful API.

Let's say we want to create an API for a todo list app we are developing Some common features that we would like:

I am going to first provide an example of a bad API.

The qualities that make it bad!

The naming is unclear and will easily confuse developers. What data are we retrieving? What kind of item are we adding? It also has poor structure and doesn't adhere to the full RESTful artchitecture (missing PUT and DELETE)

How to make it better?

This API is clear to understand and will not produce any confustion to developers. We know exactly what each method is doing and it's well defined. It also adheres to the RESTful architecture!

Proper use of HTTP Status Codes

It’s important to provide the proper status code for the request and not just a 200: OK status code whenever something works. The messages should also be meaningful in the response body Lazy Route: Return 200: OK for all of the methods.

Proper Route:

📝 Note: There are plenty more status codes that should be used for all different reasons, I am just providing these as an example of what some could be used for. Depending on the application, you may less but you should always use more than you think

Consistency

Your API should follow consistent naming conventions, HTTP methods, and error responses throughout all endpoints

Authentication and Authorization

When needed, a well structured API implements secure authentication and authorization mechanisms to protect sensitive data and actions that can be harmful. A common mechanism:

Pagination

A well structured API should always support pagination for large result sets, allowing clients to fetch data in manageable chunks. An example of pagination is any social media. When opening up twitter, a request is sent to retrieve the tweets. It would be highly inefficient to send the payload back to your phone that contains ALL the tweets from the people you’re following. This is where Pagination comes into play. Instead of getting all tweets, you may only get the most recent 20 tweets, and if you scroll through let’s say 18 of them, then it will know to fetch the next 20.

Rate Limiting

Depending on the use of the API, if its public or private, it’s important to add a rate limit. If you have a public API, this prevents someone from abusing it. One person abusing the API can drastically increase the costs and even affect the performance of other users depending on the size and computational power you have for your API. If you have a private API, its still important to set limits in the case of a bug is found that can be harmful, or to ensure costs are kept within budget.

Related: