Free Press

REST APIs permitem-lhe desenvolver qualquer tipo de aplicação web com todas as operações possíveis CRUD (criar, recuperar, actualizar, apagar). As diretrizes REST sugerem o uso de um método HTTP específico em um determinado tipo de chamada feita ao servidor (embora tecnicamente seja possível violar esta diretriz, ainda assim é altamente desencorajado).

Utilizar as informações abaixo para encontrar um método HTTP adequado para a ação executada pela API.

Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary

HTTP GET

Utilizar solicitações GET para recuperar a representação/informação de recursos apenas – e não para modificá-la de nenhuma forma. Como os pedidos GET não alteram o estado do recurso, diz-se que estes são métodos seguros. Além disso, as APIs GET devem ser idempotentes, o que significa que fazer múltiplas requisições idênticas deve produzir o mesmo resultado todas as vezes até que outra API (POST ou PUT) tenha alterado o estado do recurso no servidor.

Se o Request-URI refere-se a um processo de produção de dados, são os dados produzidos que devem ser retornados como a entidade na resposta e não o texto fonte do processo, a menos que esse texto seja a saída do processo.

Para qualquer HTTP GET API, se o recurso for encontrado no servidor, então ele deve retornar o código de resposta HTTP 200 (OK) – junto com o corpo da resposta, que normalmente é tanto conteúdo XML ou JSON (devido à sua natureza independente de plataforma).

No caso do recurso NÃO ser encontrado no servidor, então ele deve retornar o código de resposta HTTP 404 (NOT FOUND). Da mesma forma, se for determinado que a requisição GET em si não é formada corretamente, então o servidor retornará o código de resposta HTTP 400 (BAD REQUEST).

Requisição de amostra URIs

• HTTP GET http://www.appdomain.com/users
• HTTP GET http://www.appdomain.com/users?size=20&page=5
• HTTP GET http://www.appdomain.com/users/123
• HTTP GET http://www.appdomain.com/users/123/address

HTTP POST

Utilizar APIs POST para criar novos recursos subordinados, por exemplo um arquivo é subordinado a um diretório contendo-o ou uma linha é subordinada a uma tabela de banco de dados. Ao falar estritamente em termos de REST, os métodos POST são usados para criar um novo recurso na coleção de recursos.

Idealmente, se um recurso foi criado no servidor de origem, a resposta DEVERÁ ser código de resposta HTTP 201 (Created) e conter uma entidade que descreve o status da solicitação e se refere ao novo recurso, e um cabeçalho Location.

Muitas vezes, a ação executada pelo método POST pode não resultar em um recurso que possa ser identificado por um URI. Neste caso, ou o código de resposta HTTP 200 (OK) ou 204 (No Content) é o status de resposta apropriado.

Responses a este método não são armazenáveis em cache, a menos que a resposta inclua campos de cabeçalho Cache-Control apropriados ou Expires.

Por favor note que POST não é seguro nem idempotente, e invocando dois pedidos POST idênticos resultará em dois recursos diferentes contendo a mesma informação (exceto ids de recurso).

Requisição de amostra URIs

• HTTP POST http://www.appdomain.com/users337>
• HTTP POST http://www.appdomain.com/users/123/accounts

HTTP PUT

Utilizar APIs PUT principalmente para atualizar o recurso existente (se o recurso não existir, então a API pode decidir criar um novo recurso ou não). Se um novo recurso tiver sido criado pela API PUT, o servidor de origem DEVE informar o agente do usuário através do código de resposta HTTP 201 (Created) resposta e se um recurso existente for modificado, os códigos de resposta 200 (OK) ou 204 (No Content) DEVERÃO ser enviados para indicar a conclusão bem-sucedida da solicitação.

Se a solicitação passar por um cache e o Request-URI identificar uma ou mais entidades atualmente em cache, essas entradas DEVERÃO ser tratadas como obsoletas. As respostas a este método não são passíveis de cache.

Requisição de amostra URIs

• HTTP PUT http://www.appdomain.com/users/123
• HTTP PUT http://www.appdomain.com/users/123/accounts/456

HTTP DELETE

Como o nome se aplica, APIs DELETE são usadas para excluir recursos (identificados pelo Request-URI).

Uma resposta bem sucedida de pedidos DELETE DEVEM ser respostas HTTP code 200 (OK) se a resposta incluir uma entidade descrevendo o status, 202 (Accepted) se a ação foi enfileirada, ou 204 (No Content) se a ação foi executada mas a resposta não inclui uma entidade.

As operações DELETE são idempotentes. Se você APAGAR um recurso, ele é removido da coleção de recursos. APAGAR repetidamente a API do DELETE nesse recurso não irá alterar o resultado – no entanto, chamar o DELETE de um recurso uma segunda vez irá retornar um 404 (NÃO FOUND) já que ele já foi removido. Alguns podem argumentar que isso torna o método DELETE não-idempotente. É uma questão de discussão e opinião pessoal.

Se o pedido passar por uma cache e o Request-URI identificar uma ou mais entidades actualmente em cache, essas entradas DEVERÃO ser tratadas como obsoletas. As respostas a este método não são armazenáveis em cache.

Requisição de amostra URIs

• HTTP DELETE http://www.appdomain.com/users/123
• HTTP DELETE http://www.appdomain.com/users/123/accounts/456

HTTP PATCH

HTTP PATCH as requisições são para fazer atualização parcial de um recurso. Se você vir solicitações PUT também modificam uma entidade de recurso, então para deixar mais claro – o método PATCH é a escolha correta para atualizar parcialmente um recurso existente, e PUT só deve ser usado se você estiver substituindo um recurso em sua totalidade.

Por favor note que há alguns desafios se você decidir usar APIs PATCH em sua aplicação:

• Suporte para PATCH em navegadores, servidores e frameworks de aplicações web não é universal. IE8, PHP, Tomcat, Django, e muitos outros softwares têm suporte faltando ou quebrado para ele.
• Requisitar carga útil de uma requisição PATCH não é tão simples como é para a requisição PUT. e.g.

  HTTP GET /users/1

  produtos abaixo da resposta:

  {id: 1, username: 'admin', email: ''}

  Um pedido de patch de amostra para atualizar o e-mail será assim:

  HTTP PATCH /users/1

  ” }
  ]

Pode haver as seguintes operações possíveis são de acordo com a especificação HTTP.

},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]

O método PATCH não substitui os métodos POST ou PUT. Ele aplica um delta (dif) ao invés de substituir todo o recurso.

Resumo dos Métodos HTTP para APIs RESTful

A tabela abaixo resume o uso dos métodos HTTP discutidos acima.

Glossary

Safe Methods

As per HTTP specification, the GET and HEAD methods should be used only for retrieval of resource representations – and they do not update/delete the resource on the server. Ambos os métodos são considerados “seguros”.

O que permite aos agentes do usuário representar outros métodos, tais como POST, PUT e DELETE, de uma forma única para que o usuário seja alertado do fato de que uma ação possivelmente insegura está sendo solicitada – e eles podem atualizar/apagar o recurso no servidor e assim devem ser usados com cuidado.

Métodos Idempotentes

O termo idempotente é usado de forma mais abrangente para descrever uma operação que irá produzir os mesmos resultados se executada uma ou várias vezes. Idempotência é uma propriedade útil em muitas situações, já que significa que uma operação pode ser repetida ou repetida tantas vezes quantas forem necessárias sem causar efeitos não intencionais. Com operações não-idempotentes, o algoritmo pode ter que manter um registo se a operação já foi executada ou não.

Na especificação HTTP, os métodos GET, HEAD, PUT e DELETE são métodos declarados idempotentes. Outros métodos OPÇÕES e TRACE NÃO DEVEM ter efeitos secundários, portanto ambos são também inerentemente idempotentes.