Why are RESTful APIs called RESTful?

An Open Question to the Web Dev Community on the HTTP API Definition of RESTful Versus Roy Fielding’s Dissertation’s Definition of REST

What are RESTful APIs?

Seems like most web application developers would agree that the following properties define a RESTful API:

1. It follows the “proper” use of HTTP methods

• The GET method is used for idempotent non-state-altering requests for fetching resources at a given URI.
• The POST method is used for creating a new resource at a given URI.
• The PUT method is used for updating (or creating if it does not exist) a resource at a given URI.
• The PATCH method is used for a partial update of the resource at a given URI.
• The DELETE method is used for deleting the resource at a given URI.

2. Its URIs have nouns, not verbs

URIs should be noun-based with unique identifiers for single resources and allow for resource nesting

• api/v1/users is the URI for a collection of resources, in this a collection of users.
• api/v1/users/42 is the URI for the a single resource, in this case, the user with the unique identifier 42 .
• api/v1/users/42/spaceships is the URI for a nested collection of resources, in this case, all the spaceships owned by the user with unique identifier 42 .
• api/v1/users/42/spaceships/420 is the URI for a single nested resource, in this case, a single user’s single spaceship.

Examples of unRESTful APIs would be using verbs in the URI or having the id as a query string (ie. api/v1/users/create or api/v1/users/get?id=42 )

Roy Fielding’s Definition of REST

The term RESTful originates with Roy Field’s dissertation, in particular, the chapter on REST (Representation State Transfer). The chapter defines REST architecture as having the following constraints:

• Client-server Separation: … by separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components….
• Stateless: … each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server…
• Caching: … data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests
• Layered System: … the layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting…
• Code on Demand: … REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts…

So…Why are RESTful HTTP APIs called RESTful?

It doesn’t seem like the properties of a RESTful API follow from Fielding’s definition of REST. They are consistent, but it’s more to do with the HTTP protocol itself than the choice of HTTP method or use of nouns in the URI.

For example, consider the following un-RESTful API that includes the routes

• GET /api/users?id=2 to get a specific user
• POST /api/user/delete?id=4 to delete a specific user

It still satisfies the client-server separation, which is really more a property of the HTTP protocol. These requests are still stateless; each request is understood fully on its own without relying on any server state. Caching still works the same, again just a property of the HTTP Cache-Control header. The layered system is still there since the client doesn’t care if it’s talking directly to the web application, or a load balancer, or a cache layer. This API can still serve client-side scripts as code on demand.

So if an un-RESTFUL API still satisfies all the properties of Fielding’s definition of REST, then why are APIs even called RESTful in the first place?

Summary

To be clear, I’m not knocking on the RESTful API conventions. They seem like fine conventions and engineering is all about conventions. I’m just confused why they are called RESTful. Why not just call them something like the HTTP Resource Standard?

Feel free to leave corrections, comments, suggestions as comments below.