Good Practices on RESTful API Modeling (Part 3)

By Dr. Thomas Lee, CEO, Throput. This is a re-posting of a Throput blog article.

In my previous articles, I talked about the styles of modeling RESTful API in Part 1 and about designing API requests in Part 2. In this article (the final part of this series), I’ll discuss the practices of processing requests and making responses.

API Routing

Many RESTful API programming frameworks provide mechanisms for you to route API requests to handlers. (We are using Python Falcon and Django REST frameworks in our API projects.) Essentially, the routing mechanisms cover the following:

1. Map an URL pattern and the HTTP method to a handler. In some frameworks (e.g., Falcon) the URL pattern is first mapped to a class or package and the HTTP method is mapped to a function or method.
2. Define where the request parameters are embedded in the URL path. For example, the Falcon URL template /users/{username}/blogs/{blog_id} contains two arguments username and blog_id, which will be extracted from the URL path of the request and supplied to the handler method (function).

Some frameworks provide more sophisticated API routing features than the others, yet most of them function conceptually in a very similar fashion.

Body Validation

While some parameters can be provided on the URL path, other parameters and the content are mainly provided in the request body. In Part 2, I mentioned which HTTP methods (e.g., POST, PUT) might include a body. When the body is formatted in JSON, we may use JSON Schema to validate the structure and data types of JSON fields before the content is processed. Falcon supports simply using a decorator to inject the request body validation with JSON Schema. When the body of a request does not confirm to the schema, Falcon will automatically replies a 400 Bad Request response containing an automatically generated error message without actually entering the handler function. The JSON Schema is specified as a Python Dictionary. Using JSON Schema to validate the request body not only can simplify your code and but also can make it cleaner. A code snippet using Falcon is given as follows:

Constructing Response

The HTTP response essentially contains three parts: status code, response body, and response header. Some of you may only use either 200 Success or 400 Bad Request in the response when the request can be successfully handled or not, and specify the error code in the response body. Instead, we should use the HTTP status code to represent the error code whenever appropriate. Commonly used HTTP status codes and how they are used are given as follows:

In Part 2, I introduced the JSON:API specification can be followed to structure the API request, it can also be used to structure the response as well.

Lastly, we will use the HTTP response header to specify the metadata of the response. Some commonly used header fields for the RESTful API are as follows. You may refer to this Wikipedia page for the other header fields.

• Content-Type: The MIME type of the resource or the data. It is usually automatically generated by the API programming framework.
• Content-Encoding: It specifies whether and how the content is compressed.
• ETag: It is the identifier to the version of a resource. It can be a revision number or the hash value of the last modification time.
• Access-Control-Allow-Origin: It indicates whether which sites can participate in cross-origin resource sharing.
• Cache-Control: It specifies how long the result can be cached.

Summary

This short article summarizes some practices we use to process API requests and construct responses. A good API programming framework can guide you to naturally adopt these practices. If you are selecting a API framework to start with, I would recommend the Falcon Python framework, which is designed to be minimalistic and performant yet provides many useful features for simple and clean coding. As mentioned in previous articles, you should also study the Open API specification and tools, which can help you keep abreast of the latest API development standards and trends.

This article concludes the series of the Good Practices on RESTful API Modeling topic. Please leave your comments or questions here if you see I miss anything about API modeling I should have covered.