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
GETmethod is used for idempotent non-state-altering requests for fetching resources at a given URI.
POSTmethod is used for creating a new resource at a given URI.
PUTmethod is used for updating (or creating if it does not exist) a resource at a given URI.
PATCHmethod is used for a partial update of the resource at a given URI.
DELETEmethod 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/usersis the URI for a collection of resources, in this a collection of users.
api/v1/users/42is the URI for the a single resource, in this case, the user with the unique identifier
api/v1/users/42/spaceshipsis the URI for a nested collection of resources, in this case, all the spaceships owned by the user with unique identifier
api/v1/users/42/spaceships/420is 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.
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=2to get a specific user
POST /api/user/delete?id=4to 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?
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.