Good Practices on RESTful API Modeling (Part 1)

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

RESTful API development has been widely adopted for building many kinds of modern applications, such as microservices, cloud-native platforms, and open data hubs. Many tools and standards are emerging to ease API implementation. The Open API initiative and the Swagger Tools provide a cohesive set of standards and tools for API specification, coding and testing.

Before applying these tools, we need a methodology for modeling the API in a consistent way. At Throput, we have complied and developed a set of conventions and guidelines for API modeling. In this article and the following ones, I will share with you some API modeling guidelines we commonly use in software projects. In the following, I’ll introduce the resource-oriented and operation-oriented styles of API modeling, and compare their pros and cons.

As a program can be modeled in either object-oriented or functional way, a RESTful API can also be designed to be resource-oriented or operation-oriented. Although resource-oriented APIs are more common, operation-orientation may be more suitable in some applications. In fact, the GraphQL follows the operation-oriented style. As a general practice, to design a consistent and readable API, we should avoid mixing two designs in a single API.

Resource-Oriented API

A resource-oriented API binds every API endpoint (i.e., the URL) to a specific resource. For example, the API endpoint https://ex.throput.net/api/v1/users/u1122/buckets/b0905/files/hello.txt is associated with the file hello.txt under the bucket b0905 of the user u1122. The terms users, buckets, and files represent the resource types. (Note: they are commonly plural.) The terms u1122, b0905, and hello.txt represent the corresponding resource identifiers. When the resource types are well understood, they can be omitted to shorten the URL, i.e., https://ex.throput.net/api/v1/u1122/b0905/hello.txt. The following table shows the examples of resource-oriented operations.

Operation-Oriented API

An operation-oriented API binds every API endpoint to a specific operation. It is modeled like remote procedure calls (RPCs) for invocation by clients. The API path is used to catalog the operation. For example, the above example can be modeled with the operation-oriented style as follows.

Comparing Two Styles

The resource-oriented style and operation-oriented style are compared as follows.

Architecture styles

• Resource-oriented: It better conforms to the REST architecture proposed by Roy Fielding.
• Operation-oriented: To certain extent, it deviates from the REST architecture style.
• Implications: A resource-oriented API can make better use of the HTTP features, e.g., HTTP methods. A operation-oriented API only leverages a limited set of HTTP features.

Representation by an API endpoint

• Resource-oriented: It uses a noun to represent the resource.
• Operation-oriented: It uses a verb to represent the operation.
• Implications: In some cases, it might be easier to model an operation than resource. For example, multiple resources are involved in an operation; it would be easier to use the operation that compares the attributes of three products to represent the resource-oriented API.

Representation by URL path

• Resource-oriented: The URL path represents the hierarchy of a resource, e.g., a file of a bucket of a user.
• Operation-oriented: The URL path represents the path of the operation catalog, e.g., /storage/objstore/getfile.
• Implications: There are more common practices on designing API paths for the resource-oriented style.

Operations for one API endpoint

• Resource-oriented: A single API endpoint is associated with multiple operations (Create, Read, Update, Delete a.k.a. CRUD) using different HTTP methods, i.e., Put for Create, GET for Read, POST for Update, DELETE for Delete.
• Operation-oriented: A single API endpoint is associated with only one operation using either GET (for a Read operation) or POST (for other operations).
• Implications: More endpoints are often needed for an operation-oriented API. In some cases, it is not trivial for a resource-oriented API to model a non-CRUD operation, e.g., money transfer from one bank account to another account.

Request parameters and data

• Resource-oriented: The URL path contains resource IDs. The HTTP method specifies the CRUD action to perform. Additional parameters, such as special operation to perform, filtering options, are given in the query string, e.g., date=2018-05-29 in https://ex.throput.net/api/v1/u1122/b0908/?createdate=2018-05-29. The HTTP request body contains the data payload.
• Operation-oriented: The URL path usually does not contain data. Simple operation parameters are specified in query string, e.g., resource IDs. Complex operation data are given in the HTTP Request body.
• Implications: A resource-oriented API can use the API path to identify a resource by using the resource ID. However, it is more straightforward for an operation-oriented API to represent request all data in the request body (or the query parameters).

Cachability

• Resource-oriented: Since an API endpoint represents a resource, it is easily for the clients or Content Delivery Networks (CDNs) to cache the resource states, e.g., by using ETags.
• Operation-oriented: It is not trivial for the client to determine what operation results to cache.
• Implications: The cachability of a resource-oriented API is generally better than an operation-oriented API.

Summary

There are not hard rules to follow for choosing the resource-oriented style or the operation-oriented style to model our application. In general the HTTP features (e.g., methods and headers) are better supported by the resource-orientation. Also more industry tools and good practices follow this style. Therefore, we may pick this style by default and verify if there are major modeling issues. If so, we may consider the operation-orientation. Or it is possible that the GraphQL standard just meets our business needs.