What does a well structured API look like?

💡 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:

• to see our to-do's
• update our to-do's
• remove a to-do
• create a new to-do

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

• GET /data : retrieves data
• POST /add : adds a new item

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?

• GET /todo : retrieves our list of to-do's and only those
• POST /todo : adds a new to-do
• PUT /todo/:id : updates a to-do
• DELETE /todo/:id : deletes a to-do

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.

• very difficult to debug
• confustion when displaying errors

Proper Route:

• GET: should return...
  • 200 when its successful
  • 401 if a user is authorized to view them
  • 500 if the user has had an error
• POST: should return...
  • 201 when created
  • 400 if incorrect syntax
  • 401 if a user is unauthorized to create them
  • 500: Error adding to ... if there is some problem with storing it
• PUT: ...
• Delete: ...

📝 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:

• API Keys - where in order to use an API, you can generate one that is passed into the request headers and the API then verifies that its valid.

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.