Nem só de GET, POST, PUT e DELETE vive uma API

 

Olha eu aqui no blog da QALab de novo! Seguindo a série de posts sobre APIs, hoje vou falar um pouco sobre um quinto verbo HTTP.

Os verbos (ou métodos) HTTP mais comuns são (definições de acordo com a RFC 2616):
verbos_http
GET – recupera qualquer informação (sob a forma de uma entidade) identificada pelo Request-URI.

POST – solicita que o servidor de origem aceite a entidade no pedido como um novo subordinado do recurso identificado pelo Request-URI.
PUT – solicita que a entidade enviada seja armazenada sob a Request-URI. Se o Request-URI se refere a um recurso existe, a entidade completa enviada deve ser considerada como uma versão modificada do recurso.
DELETE – solicita que o recurso identificado no Request-URI seja apagado.

Vamos falar um pouco de outro verbo definido na RFC 5789: PATCH.

O que ele faz? Atualiza uma entidade. Mas espera.. O PUT já não faz isso? Sim, e portanto vamos dar uma definição mais completa para o PATCH, que permitirá uma comparação melhor com o PUT.

O verbo PATCH envia um conjunto de alterações a serem aplicadas no recurso identificado pela URI. Esse conjunto contém instruções sobre como um recurso atualmente residindo no servidor de origem deve ser modificado para produzir uma nova versão.

O verbo PUT envia uma entidade que é considerada uma versão modificada do recurso no servidor de origem e faz uma requisição para que a versão armazenada seja alterada.

Com exemplos tudo fica mais fácil. Vamos pensar em uma API de uma checklist. Minha primeira chamada vai ser para criar um item nessa lista.

POST /checklist/items
{ “name”: “Preparar blog post sobre PATCH”,
“dueDate”: “15/04/2015”}
Return code: 201

Quando faço uma chamada à API agora para ver a minha checklist, uso um GET e a seguinte informação é devolvida:

Return code: 200
[ { “id”: 1,
“name”: “Preparar blog post sobre PATCH”,
“dueDate”: “15/04/2015”,
“createdAt”: “14/04/2015”,
“status”: “pending”}]

Quando eu terminar de escrever esse artigo, vou querer atualizar o status desse item.

Se eu atualizar o item utilizando PUT, vou precisar mandar todos os campos de volta, mudando apenas o status para completed. Enviar o objeto inteiro em um PUT pode implicar problemas de performance (tempo de envio/resposta) e carga (consumo de banda para envio de dados). Claro que no caso da checklist estamos trabalhando com um objeto muito pequeno, mas muitas vezes no mundo real as aplicações com as quais lidamos são mais complexas.

PUT /checklist/items/1
{ “id”: 1,
“name”: “Preparar blog post sobre PATCH”,
“dueDate”: “15/04/2015”,
“createdAt”: “14/04/2015”,
“status”: “completed”}
Return code: 200

Essa alteração usando PATCH seria assim:

PATCH /checklist/items/1
[ { "op": "replace", "path": "/status", "value": "completed" } ]
Return code: 204

(de acordo com a RFC 5789, ou ainda, 200)

Resumo sobre o verbo PATCH:

O verbo PATCH envia um conjunto de alterações a serem aplicadas no recurso identificado.

 

Como não usar PATCH:

Enviando apenas um update direto, sem instruções

PATCH /checklist/items/1
{ "status": "completed" }

ou

PATCH /checklist/1?status=completed

Como usar PATCH:

PATCH /checklist/items/1
[ { "op": "replace", "path": "/status", "value": "completed" }

E há mais posts sobre APIs no forno! Em breve, mais um artigo aqui no blog da QALab.

3 thoughts on “Nem só de GET, POST, PUT e DELETE vive uma API

  • Perfeito Sarah!!!
    Tenho trabalhado a um bom tempo com automação de teste em APIs Rest e tenho usado os seus posts para inspiração para a galera de QA novos que tem me pedido referências para iniciar estudos sobre testes de API 🙂
    Parabéns!

Deixe uma resposta

O seu endereço de email não será publicado. Campos obrigatórios marcados com *

*