REST

A way to expose your application endpoints

Simple and stateless way to syncronously communicate with services.

It is possible to cache data.

Levels of Maturity

Level 0

Only states that all traffic over HTTP has a purpose to execute a transaction.

(Like do something on DB, or call for execution of a procedure)

There is no level of pattern in it's use.

Level 1

Start using resources.

Verb	URI	Operation
GET	/products/1	Retrieve Info
POST	/products	Insert
PUT	/products/1	Alter
DELETE	/products/1	Remove

Level 2

When you organize and make sure you use the correct verb for the correct operation, in each URI.

This means for instance, no updates with POST.

Leve 3

HATEOAS (Hypermedia as the Engine of Application State)

Not only awnsers your request, but also, brings others things that you can do from what you just did.

response

{
  "account": {
    "account_number": 1234,
    "balance": {
      "currency": "brl",
      "value": 500.00
    },
    "links": {
      "deposit": "/accounts/1234/deposit",
      "withdraw": "/accounts/1234/withdraw",
      "close": "/accounts/1234/close",
    }
  }
}

Good Practices

• Use unique URIs for each exposed service.

• Use the correct verbs to execute the correct actions.

• Provide links exemplifying how to use the API.

Response Patterns

Just JSON doesn't provides a hypermedia pattern for responses.

HAL

(Hypermedia Application Language)

Media Type: application/hal+json

In this pattern, besides providing the data from the requested service, it also provides:

• _links that always tells you the current resource you are accessing. (self).

• There is also an _embedded that can bring related data from the main data.

response

{
  "_links": {
    "self": {
      "href": "http://url/api/user/bill"
    }
  },
  "id": "s9-s0dsf-12fasd",
  "name": "Bill Someone",
  "_embedded": {
    "family": {
      "_links": {
        "self": {
          "href": "http://url/api/user/maria"
        }
      },
      "id": "asd9-asfasd9",
      "name": "Maria Else"
    }
  }
}

Collection+JSON

Siren

Method Negotiation

HTTP has an OPTIONS method. This method allows us to inform which methods are allowed or not in each resource.

Ex.:

request

OPTIONS /api/product HTTP/1.1
Host: url.com

OPTIONS anwser could be:

response

HTTP/1.1 200 OK
Allow: GET, POST

If request sent to this same URI was invalid, like a PUT:

response

HTTP/1.1 405 Not Allowed
Allow: GET, POST

Content Negotiation

The content negotiation process is based on the request the client is doing to the server.

In this case, the user request what and how he wants the anwser to be. The server then might or might not return the request in the desired format.

Accept Negotiation

The client requests the data and the return type, based on a given media type in order of priority.

Ex.:

request

GET /product
Accept: application/json

The anwser could be:

response

HTTP/1.1 406 Not Acceptable

Content-Type Negotiation

Through a content-type in the request header, the server can verify is it will be able to process the data to return.

request

POST /product HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "name": "Product 1"
}

In case the server doesn't support the content-type it can return:

response

HTTP/1.1 415 Unsupported Media Type