REST é o princípio arquitetônico subjacente da web. O mais surpreendente da Web é o fato de que clientes (navegadores) e servidores podem interagir de maneiras complexas sem que o cliente saiba nada de antemão sobre o servidor e os recursos que ele hospeda. A principal restrição é que o servidor e o cliente devem concordar com a mídia usada, que no caso da Web é HTML .
Uma API que segue os princípios do REST não exige que o cliente saiba nada sobre a estrutura da API. Em vez disso, o servidor precisa fornecer todas as informações que o cliente precisa para interagir com o serviço. Um formulário HTML é um exemplo disso: O servidor especifica o local do recurso e os campos obrigatórios. O navegador não sabe com antecedência onde enviar as informações e não sabe com antecedência quais informações enviar. Ambas as formas de informação são totalmente fornecidas pelo servidor. (Esse princípio é chamado HATEOAS : Hipermídia como o mecanismo do estado do aplicativo .)
Então, como isso se aplica ao HTTP e como ele pode ser implementado na prática? O HTTP é orientado em torno de verbos e recursos. Os dois verbos em uso mainstream são GETe POST, que eu acho que todos reconhecerão. No entanto, o padrão HTTP define vários outros, como PUTe DELETE. Esses verbos são aplicados aos recursos, de acordo com as instruções fornecidas pelo servidor.
Por exemplo, vamos imaginar que temos um banco de dados do usuário gerenciado por um serviço da web. Nosso serviço usa uma hipermídia personalizada baseada em JSON, para a qual atribuímos o tipo mimético application/json+userdb(também pode haver um application/xml+userdbe application/whatever+userdb- muitos tipos de mídia podem ser suportados). O cliente e o servidor foram programados para entender esse formato, mas não sabem nada um do outro. Como Roy Fielding aponta:
Uma API REST deve gastar quase todo o seu esforço descritivo na definição do (s) tipo (s) de mídia usado para representar recursos e direcionar o estado do aplicativo, ou na definição de nomes de relações estendidos e / ou marcação ativada por hipertexto para os tipos de mídia padrão existentes.
Uma solicitação para o recurso base /pode retornar algo como isto:
Solicitação
GET /
Accept: application/json+userdb
Resposta
200 OK
Content-Type: application/json+userdb
{
"version": "1.0",
"links": [
{
"href": "/user",
"rel": "list",
"method": "GET"
},
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
Sabemos pela descrição de nossa mídia que podemos encontrar informações sobre recursos relacionados nas seções chamadas "links". Isso é chamado de controles Hypermedia . Nesse caso, podemos dizer a partir de uma seção como essa que podemos encontrar uma lista de usuários fazendo outra solicitação para /user:
Solicitação
GET /user
Accept: application/json+userdb
Resposta
200 OK
Content-Type: application/json+userdb
{
"users": [
{
"id": 1,
"name": "Emil",
"country: "Sweden",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
{
"id": 2,
"name": "Adam",
"country: "Scotland",
"links": [
{
"href": "/user/2",
"rel": "self",
"method": "GET"
},
{
"href": "/user/2",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/2",
"rel": "delete",
"method": "DELETE"
}
]
}
],
"links": [
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
Podemos dizer muito dessa resposta. Por exemplo, agora sabemos que podemos criar um novo usuário POSTao /user:
Solicitação
POST /user
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Karl",
"country": "Austria"
}
Resposta
201 Created
Content-Type: application/json+userdb
{
"user": {
"id": 3,
"name": "Karl",
"country": "Austria",
"links": [
{
"href": "/user/3",
"rel": "self",
"method": "GET"
},
{
"href": "/user/3",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/3",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
Também sabemos que podemos alterar os dados existentes:
Solicitação
PUT /user/1
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Emil",
"country": "Bhutan"
}
Resposta
200 OK
Content-Type: application/json+userdb
{
"user": {
"id": 1,
"name": "Emil",
"country": "Bhutan",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
Observe que estamos usando diferentes verbos HTTP ( GET, PUT, POST, DELETEetc.) para manipular esses recursos, e que o único conhecimento presumimos por parte do cliente é a nossa definição de mídia.
Leitura adicional:
(Essa resposta foi alvo de uma grande quantidade de críticas por ter falhado o argumento. Na maioria das vezes, essa foi uma crítica justa. O que eu descrevi originalmente estava mais de acordo com a maneira como o REST era geralmente implementado alguns anos atrás, quando eu primeiro escrevi isso, em vez de seu verdadeiro significado. Revi a resposta para representar melhor o significado real.)
