How RESTful is your service?

Web services are everywhere these days, from social media platforms to enterprise line-of-business solutions. It is extremely important to be able to expose APIs for your solution, in order to reach more external consumers on multiple platforms. As a modern trend, we see that more and more APIs are surfacing claiming to be RESTful, but in fact, they're actually just good old remote procedure calls (RPC).

Many of these proclaimed "REST"-style services are implemented not even knowing what the term means, so I've decided to help try explain REST and how to get your services RESTful.

REST and RESTful

Developed by Roy Fielding, Representational State Transfer (or REST) is a style of software architecture for distributed systems, such as the Web, and it relies on a stateless, client-server, cache-able communications protocols, like HTTP.

/this/does/not/mean/restful, { "neither":"does this" }

Having an API with clean fluent routes and that returns JSON does not necessarily make your service RESTful. Only when adopting REST as a style and conforming to certain rules will make a service truly RESTful.

Fielding outlines six constraints that are required for REST. At least 5 of the constraints need to be respected to have a service be considered as RESTful:

1. Client-Server constraint

Clients and servers are separated by an uniform interface which allows for a client not to be concerned with business logic and data storage, and likewise, a server is not concerned with the user interface.

2. Stateless constraint

Each request made to the server contains all the information needed by the server to service the request, thus no state is stored on the server.

3. Cache-able constraint

Responses must be able to, explicitly or implicitly, define themselves as cache-able, to allow the client to re-use responses, eliminating round-trips to the server, thus improving performance.

4. Layered System constraint

The client is oblivious to the use of intermediary components, such as load balancers and proxies, improving system scalability.

5. Uniform Interface constraint

This is the most unique feature of REST and allows interaction between client and server in a uniform way by identifying resources from the request URI and modifying them using HTTP verbs. As mentioned earlier, each message contains enough information on how to process the request and uses HATEOAS as the engine for application state.

6. Code On Demand constraint

This optional constraint allows a client to not know how to process the resource until it is retrieved and locally executed. This is typically used to dynamically add features to deployed applications.

RESTful Web APIs

Web-based application programming interfaces implementing REST and HTTP principles are known as RESTful Web APIs and contains the following properties:

• A base URI, for example http://api.mysystem.com
• A supported internet media type, like JSON
• Operations using HTTP verbs GET, POST, PUT and DELETE
• Hypertext driven

A RESTful Web API must be simple and easy to use and must provide useful documention. Remember: "If you have to ship an SDK for your RESTful API, it is not a RESTful API"  -source

The ASP.NET team developed a framework for building Web APIs based on REST principles, called ASP.NET Web API. You can read more on this here.

That's a wrap

The constraints described above are not considered a standard, but rather as best practice guidelines to follow, in order to build rich RESTful services for the modern web. 

There are only a handful of APIs that are truly RESTful, the majority are really modified RCP over HTTP. So next time you explore a new API, feel free to compare notes and find out if it is a true RESTful service.

@FanieReynders