According to Roy Fielding, one of the REST architecture model creator, to an API be considered as RESTful it needs strictly to follow a set of constraints predefined in his papers first.
Those constraints are based on:
- Resource identification (URI)
- Resource representations and use of media-types
- Use of header and body on message
- Hypermedia (Links & Forms)
Sometimes, we could find ourselves in tricky situations when implementing this set of constraints by Roy in a APIs, and what actually really matters is a simple approach aiming RESTful.
The main focus of this post is to discuss about Leonard Richardson model, which exactly explains how to develop complex APIs but still keeping it simple and RESTful.
The Richardson maturity model is separated in four (not so tough) levels, The question that you need to make right now is, "Are you ready to climb until the top of pyramid?"
Level 0 - POX
The farthest level of a RESTful API and there is no standard type used here. Resources are not well defined, and are being used only to invoke remote mechanisms based on remote procedure call. The exchange messages at this level can be serialized in XML, JSON, text, and other formats. This level does not make an API RESTful.
Let's imagine a CRUD (create, delete, update and delete) interface based to maintain customer data. In the RPC POX model it would look like this:
RPC POX
| HTTP verb | URI | Operation |
|---|---|---|
| GET | /getCustomer/1 | Get data |
| POST | /saveCustomer | Create |
| POST | /changeCustomer/1 | Change |
| GET/POST | /deleteCustomer/1 | Delete |
Although is the most model used, it only uses GET and POST verbs, and the resources name are not well formatted. So ... nothing to do with REST.
Level 1 - Resources
At this level, we will start using features as a way to model and organize the RESTful API. Necessarily, we do not need to know the functionality attached in each method, but we should know how to identify resources.
Let's imagine the same customer interface with CRUD operations. By modeling resources correctly, we only need to know which HTTP method to use in order to interact with resources.
REST
| HTTP verb | URI | Operation |
|---|---|---|
| GET | /customer/1 | Get data |
| POST | /customer | Create |
| PUT | /customer/1 | Change |
| DELETE | /customer/1 | Delete |
Level 2 - HTTP verbs
On this moment, the HTTP verbs are begin to be used for which they were actually created. The most used verbs are GET, POST, PUT and DELETE.
By default, GET is classified as an safe operation, by not making any relevant changes in resources when executed. This allows us to invoke GET securely as much as we needed.
// Request:
GET /customer/1
// Response:
HTTP/1.1 200 OK
{
name: "ACME"
}// Request:
POST /customer
{
name: "ACME"
}
// Response:
HTTP/1.1 201 Created
{
name: "ACME"
}// Request
PUT /customer
{
name: "ACME",
address: "Some street"
}
// Response:
HTTP/1.1 200 OK
{
name: "ACME",
address: "Some street"
}// Request
DELETE /customer/1
// Response:
HTTP/1.1 204 No ContentFor a complete list of HTTP status codes, access the Mozilla Developer Network - HTTP Status Code.
Level 3 - HATEOAS
Also known as Hypermedia as the Engine of Application State, Roy Fielding describes HATEOAS as one of the necessary premises to consider an API as RESTful.
Its main element is the hypermedia representation, allowing a document to describe its current state, and its relationship with other elements or future states. Please, understand HATEOAS as the ability of a document to be relate with others.
// Request
GET /customer/1
// Response:
HTTP/1.1 200 OK
{
name: "ACME",
links: [ {
rel: "self",
href: "http://localhost:8080/customer/1"
}, {
rel : "delete",
href: "http://localhost:8080/customer/1"
]
}Notice that customer resource has hypermedia (links) that points to himself (current state) and also points to a possible deletion (future state). The most important point of hypermedia controls is the way a resource is self-explanatory handled, and there is no need to guess which operations are enabled in a resource.
Do not confuse REST with RESTful
There is a slightly difference between both REST and RESTful. The first one means about a set of best practices (Roy's constraint), while RESTful is the implementation of those constraints in an API. It means, when an API is constructed based on those constraints, it automatically becomes RESTful.
You could find that more on Chapter 5 - Representational State Transfer on Roy's papers.
References
RICHARDSON, LEONARD. Richardson Maturity Model. https://martinfowler.com/articles/richardsonMaturityModel.html, 2010
- SAP Managed Tags:
2 Comments
