(0.1)
The following diagram illustrates my thinking when designing an API.
Stack Overflow is flooded with debates on what constitutes good API design, what is and isn’t considered RESTful, and if RPC is a relic of the past or the way of the future (again).
Here is the definitive definition of REST, from its creator;
REST is not an architecture, but rather an architectural style. It is a set of constraints that, when adhered to, will induce a set of properties; most of those properties are believed to be beneficial for decentralized, network-based applications, while others are the negative trade-offs that can result from any design choice (any constraint implies that a designer’s space of choices is reduced). REST does not directly constrain the Web’s architecture. Rather, an application developer may choose to constrain an architecture in accordance with the REST style. There is no way to force adherence to the REST constraints, though some poorly considered applications might not work well without them. – Reflections on the REST Architectural Style and “Principled Design of the Modern Web Architecture”, Roy T Fielding, et al.
That’s a mouthful. Many developers have read that paper and Roy Fielding’s original dissertation on REST – I hadn’t for years. Others read only what is written second or third hand on sites like Stack Overflow and Reddit where REST is generally misunderstood to be a general architecture that describes how to build APIs on top of HTTP. Roy Fielding’s Misappropriated REST Dissertation gives a great assessment on how this came about.
Nothing beats the HTTP protocol for allowing a web-server to communicate with and server web pages to any web browser. Here’s the HTTP definition from Wikipedia;
HTTP (Hypertext Transfer Protocol) is an application layer protocol in the Internet protocol suite model for distributed, collaborative, hypermedia information systems.[1] HTTP is the foundation of data communication for the World Wide Web, where hypertext documents include hyperlinks to other resources that the user can easily access, for example by a mouse click or by tapping the screen in a web browser. – HTTP (Wikipedia)
Per Roy Fielding’s original dissertation on REST, REST is fundamentally;
- Client-server
- Stateless
- Supports Caching
- Uniform Interface
- Layered
- Code-On-Demand
These describe the web. REST does not prescribe how to build APIs on top of HTTP. REST describes the architectural constraints one should follow when building systems that work just like a web-server serving web pages to a browser; everything is a resource with HTTP methods being the mechanism by which resource state transitions – and therefore application state transitions, i.e. business logic – are implemented.
If you are developing a web app and your architectural constraints are the same as, or similar to those of a web browser and web-server, then you could to worse than follow the REST architectural style. Because the REST architectural style is really great for this use-case – the web use-case.
However, there is no need to adhere to the REST style when building, for example, a native mobile app that communicates with a set of back-end services. Different constraints means there is no architectural reason, other than to claim that your API is “RESTful”, to mangle an API to expose a fancifully conceived “resource” where there exists no such resource in the back-end, so as to have a object for the HTTP methods to operate on.
We should accept that RPC simplifies the designs for many real world use cases that cannot be adequately captured as a resource operated on by the HTTP PUT, GET, DELETE, and UPDATE methods, and architect accordingly. And then use POST, always returning a HTTP 200 OK response to each request processed by the service.
Our RPC POST service, that’s 100% definitely not “RESTful”, should return only HTTP 200 OK for all cases and include in the response body an application specific status code that defines how the client is to interpret the response. To the effect of;
{
"error": 0,
"error_description": "success",
"data": {}
}
The other HTTP status codes; 201, 404, 500, etc. are returned by the other layers in the stack; SPRING, Apache Tomcat, proxies, load balancers, API Gateways, and other software or hardware components that sit between the service and the client.