REST - Verbos HTTP

  Vamos apresentar neste artigo os principais verbos HTTP usados em APIs REST como funcionam e suas características.

Uma API REST (também conhecida como API RESTful) é uma interface de programação de aplicativos (API ou API Web) que está em conformidade com as restrições do estilo de arquitetura REST e permite a interação com serviços Web RESTful.

O termo REST significa REpresentational State Transfer ou Transferência de Estado Representacional e foi criado pelo cientista da computação Roy Fielding.

Uma API REST pode ser usada por vários clientes para se comunicar com um servidor sendo um tipo de serviço web que armazena e recupera os dados necessários; para acessar os endpoints de uma API REST usamos os verbos HTTP.

Assim quando planejamos a criação de uma API REST devemos definir quais os endpoints deverão ser criados para acessar os recursos e para ações específicas.

Como exemplo suponha que vamos criar uma API REST para gerenciar recursos que serão definidos como informações sobre carros, e,  que desejamos realizar ações como obter uma lista dos carros, obter um carro de forma única, criar um novo carro, alterar os dados existentes para um carro, alterar uma informações específica de carro e excluir um carro existente.

Podemos de forma bem simples representar a definição dos endpoints , dos verbos HTTP usados e das ações desejadas nesta API usando a seguinte tabela:

Endpoint Verbo HTTP/Método Ação Esperada Retorno esperado (Status Code)
/carros GET Retorna uma lista de carros 200 OK
/carros POST Inclui um novo carro 201 Created
/carros/{id}    GET Retorna um carro pelo seu id 200 OK
/carros/{id}   PUT Substitui dados do carro pelo id 200 OK ou 204 No Content
/carros/{id}   PATCH Altera informações específicas de um carro pelo id 200 OK ou 204 No Content
/carros/{id}   DELETE Remove um carro pelo id 200 OK

Nota: Os Status Code retornados quando a operação falha podem ser:

Para obter uma lista dos Código de Status HTTP consulte aqui.

Além dos verbos usados existem ainda os verbos HTTP : HEAD e OPTIONS.

Características de cada verbo HTTP

1- POST

O verbo POST é usado com mais frequência para **criar** novos recursos. Em particular, é usado para criar recursos subordinados. Ou seja, subordinado a algum outro recurso (por exemplo, pai). Em outras palavras, ao criar um novo recurso, POST para o pai e o serviço se encarrega de associar o novo recurso ao pai, atribuir um ID (novo URI de recurso), etc.

Na criação bem-sucedida, retorna o status HTTP 201, retornando um cabeçalho Location com um link para o recurso recém-criado com o status HTTP 201.

POST não é seguro pois alterar o estado do recurso no servidor, nem idempotente, e portanto, é recomendado para solicitações de recursos não idempotentes. Fazer duas solicitações POST idênticas provavelmente resultará em dois recursos contendo as mesmas informações.

2- GET

O método HTTP GET é usado para **ler** (ou recuperar) uma representação de um recurso. No caminho feliz (ou sem erro), GET retorna uma representação em XML ou JSON e um código de resposta HTTP de 200 (OK). Em um caso de erro, na maioria das vezes ele retorna um 404 (Not Found) ou 400 (Bad Request).

De acordo com o design da especificação HTTP, as solicitações GET (e HEAD) são usadas apenas para ler dados e não alterá-los. Portanto, quando usados dessa forma, são considerados seguros. Ou seja, eles podem ser chamados sem risco de modificação ou corrupção de dados - chamá-los uma vez tem o mesmo efeito que chamá-los 10 vezes, ou nenhum. Além disso, GET (e HEAD) é idempotente, o que significa que fazer várias requisições idênticas acaba tendo o mesmo resultado de uma única requisição.

Não exponha operações inseguras via GET — ele nunca deve modificar nenhum recurso no servidor.

3- PUT

PUT é usado com mais frequência para recursos de **atualização**,  enviado para uma URI de um recurso conhecido com o corpo da solicitação contendo a representação recém-atualizada do recurso original. Assim PUT exige o envio completo do recurso.

No entanto, PUT também pode ser usado para criar um recurso no caso em que o ID do recurso é escolhido pelo cliente em vez do servidor. Ou seja, se o PUT for para uma URI que contenha o valor de um ID de recurso inexistente. Novamente, o corpo da solicitação contém uma representação de recurso. Muitos acham que isso é complicado e confuso. Por isso, este método de criação usando PUT deve ser usado com moderação, se for o caso.

Na atualização bem-sucedida, retorna 200 (ou 204 se não estiver retornando nenhum conteúdo no corpo). Se estiver usando PUT para criar, retorne o status HTTP 201 na criação bem-sucedida. Um corpo na resposta é opcional e não é necessário retornar um link por meio de um cabeçalho Location no caso de criação, pois o cliente já definiu o ID do recurso.

PUT não é uma operação segura, pois modifica (ou cria) o estado no servidor, mas é idempotente. Ou seja, se você criar ou atualizar um recurso usando PUT e fizer a mesma chamada novamente, o recurso ainda estará lá e ainda terá o mesmo estado da primeira chamada.

Se, por exemplo, chamar PUT em um recurso que incrementa um contador dentro do recurso, a chamada não é mais idempotente. Às vezes isso acontece e pode ser suficiente para documentar que a chamada não é idempotente. No entanto, é recomendável manter as solicitações PUT idempotentes.

4- PATCH

PATCH é usado para **modificar** recursos. A solicitação PATCH só precisa conter as alterações no recurso, não o recurso completo.

Isso se assemelha a PUT, mas o corpo contém um conjunto de instruções que descrevem como um recurso que reside atualmente no servidor deve ser modificado para produzir uma nova versão. Isso significa que o corpo do PATCH não deve ser apenas uma parte modificada do recurso, mas em algum tipo de linguagem de patch como JSON Patch ou XML Patch.

PATCH não é seguro nem idempotente. No entanto, uma solicitação PATCH pode ser emitida de forma idempotente, o que também ajuda a evitar resultados ruins de colisões entre duas solicitações PATCH no mesmo recurso em um período de tempo semelhante.

As colisões de várias solicitações PATCH podem ser mais perigosas do que as colisões PUT porque alguns formatos de patch precisam operar a partir de um ponto base conhecido ou corromperão o recurso. Os clientes que usam esse tipo de aplicativo de patch devem usar uma solicitação condicional de modo que a solicitação falhe se o recurso tiver sido atualizado desde a última vez que o cliente acessou o recurso.

5- DELETE

O DELETE é usado para **excluir** um recurso identificado por um URI.

Na exclusão bem-sucedida, retorna o status HTTP 200 (OK) junto com um corpo de resposta, talvez a representação do item excluído ou uma resposta agrupada, ou retornar o status HTTP 204 (SEM CONTEÚDO) sem corpo de resposta.

Em termos de especificação HTTP, as operações DELETE são idempotentes. Se você EXCLUIR um recurso, ele será removido. Chamar repetidamente DELETE nesse recurso acaba da mesma forma: o recurso se foi. Se chamar DELETE digamos, decrementa um contador (dentro do recurso), a chamada DELETE não é mais idempotente.

Há uma ressalva sobre a idempotência DELETE, no entanto. Chamar DELETE em um recurso uma segunda vez geralmente retornará um 404 (NOT FOUND), pois ele já foi removido e, portanto, não é mais localizável. Isso, segundo algumas opiniões, faz com que as operações DELETE não sejam mais idempotentes, no entanto, o estado final do recurso é o mesmo. Retornar um 404 é aceitável e comunica com precisão o status da chamada.

Métodos HEAD e OPTIONS

Embora sejam pouco usados vejamos como atuam estes dois verbos HTTP.

- HEAD

O método HEAD retorna informações sobre o recurso (version/length/type)

O método HEAD é idêntico ao GET, exceto que o servidor NÃO DEVE retornar um corpo de mensagem na resposta. A metainformação contida nos cabeçalhos HTTP em resposta a um pedido HEAD DEVE ser idêntica à informação enviada em resposta a um pedido GET.

Este método pode ser usado para obter metainformações sobre a entidade implícita na solicitação sem transferir a própria entidade-corpo. Esse método é frequentemente usado para testar links de hipertexto quanto à validade, acessibilidade e modificação recente.

Exemplo de response para HEAD:

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: text/html; charset=UTF-8
Date: Wed, 08 May 2013 10:12:29 GMT
ETag: "780602-4f6-4db31b2978ec0"
Last-Modified: Thu, 25 Apr 2013 16:13:23 GMT
Content-Length: 1270

- OPTIONS

O método OPTIONS representa uma solicitação de informações sobre as opções de comunicação disponíveis na cadeia de solicitação/resposta identificada pelo Request-URI. (Informa quais métodos são permitidos pelo recurso.)

Este método permite que o cliente determine as opções e/ou requisitos associados a um recurso, ou os recursos de um servidor, sem implicar em uma ação de recurso ou iniciar uma recuperação de recurso.

As respostas a esse método não podem ser armazenadas em cache.

Exemplo de response para OPTIONS:

HTTP/1.1 200 OK
Allow: GET,HEAD,POST,OPTIONS,TRACE
Content-Type: text/html; charset=UTF-8
Date: Wed, 08 May 2013 10:24:43 GMT
Content-Length: 0

E estamos conversados...

"A ti, ó Deus, glorificamos, a ti damos louvor, pois o teu nome está perto, as tuas maravilhas o declaram"
Salmos 76:1

Referências:

José Carlos Macoratti