Métodos HTTP Spring REST

Padrões REST

A Representational state transfer ( REST ) é um estilo de arquitetura de software que define um conjunto de restrições a ser usado para criar serviços da web. Serviços da Web que estão em conformidade com o estilo de arquitetura REST, chamados de serviços da Web RESTful (ou simplesmente serviços RESTful ).

Os serviços RESTful nos permitem desenvolver qualquer tipo de aplicativo envolvendo todas as operações CRUD (create, read, update, delete) possíveis. Devemos utilizar os diferentes verbos HTTP que correspondem às operações CRUD. Os métodos HTTP principais ou mais comumente usados ​​são GET, POST, PUT, PATCH e DELETE. Na execução dessas operações em serviços RESTful , existem diretrizes ou princípios que sugerem o uso de um método HTTP específico em um tipo específico de chamada feita ao servidor.

De vez em quando ficamos na duvida de qual resposta retornar
Abaixo está uma tabela que resume os métodos HTTP primários e suas recomendações para serviços RESTful :

GET

O método GET usado para recuperar informações da API REST e não modificá-las de forma alguma. GET deve ser um método seguro e idempotente. Métodos seguros (e idempotência) podem ser armazenados em cache.

• Se o recurso for encontrado no servidor, ele deve retornar o código de resposta HTTP 200 (OK) — junto com o corpo da resposta (pode ser XML, JSON ou (possível) RAW)
• Caso o recurso NÃO seja encontrado no servidor, ele deve retornar 404 (não encontrado).
• Caso a própria solicitação GET não seja formada corretamente, o servidor retornará 400 (Solicitação inválida).

Um exemplo

PS: não vamos nos aprofundar em outra área, como acesso a banco de dados, serviços, etc.

Curl deGET:

curl -X GET "http://localhost:8080/spring-rest-examples/rest/v1/books" -H "accept: */*"

Response body — 200 (OK)

[
  {
    "id": 1,
    "oclc": "1827184",
    "isbn10": null,
    "isbn13": null,
    "title": "The Hobbit"
  },
  {
    "id": 2,
    "oclc": "1487587",
    "isbn10": null,
    "isbn13": null,
    "title": "The Lord of The Rings"
  },
  {
    "id": 3,
    "oclc": "3318634",
    "isbn10": "0048231398",
    "isbn13": null,
    "title": "The Silmarillion"
  },
  {
    "id": 4,
    "oclc": "7207376",
    "isbn10": null,
    "isbn13": null,
    "title": "The Lion, the Witch, and The Wardrobe"
  },
  {
    "id": 5,
    "oclc": "2812448",
    "isbn10": null,
    "isbn13": "9780006716792",
    "title": "Prince Caspian"
  },
  {
    "id": 6,
    "oclc": "2805288",
    "isbn10": null,
    "isbn13": "9780006716808",
    "title": "The Voyage of the Dawn Treader"
  },
  {
    "id": 7,
    "oclc": "1304139",
    "isbn10": null,
    "isbn13": "9780006716815",
    "title": "The Silver Chair"
  },
  {
    "id": 8,
    "oclc": "2801054",
    "isbn10": null,
    "isbn13": "9780006716785",
    "title": "The Horse and His Boy"
  },
  {
    "id": 9,
    "oclc": "2497740",
    "isbn10": null,
    "isbn13": "9780006716839",
    "title": "The Magician's Nephew"
  },
  {
    "id": 10,
    "oclc": "752428300",
    "isbn10": null,
    "isbn13": "9780006716822",
    "title": "The Last Battle"
  }
]

GET unico id :

curl -X GET "http://localhost:8080/spring-rest-examples/rest/v1/books/5" -H "accept: */*"

Response body — 200 (OK)

{
  "id": 5,
  "oclc": null,
  "isbn10": null,
  "isbn13": "9780006716792",
  "title": "Prince Caspian"
}

POST

O POST deve ser usado apenas para criar um novo recurso. Em alguns casos, o método POST é usado para atualizar a entidade, mas temos um método HTTP mais adequado para fazer isso (PUT). A chamada POST API não é idempotente nem segura e deve ser usada com cuidado. Invocar duas solicitações POST idênticas resultará na criação de dois recursos diferentes com as mesmas informações, mas com IDs de recursos diferentes

• Se um recurso for criado no servidor, a resposta idealmente deve ser o código de resposta HTTP 201 (criado), um cabeçalho de localização (URI) e conter uma entidade que descreve o status da solicitação e se refere ao novo recurso
• No caso de criação bem-sucedida, mas o recurso não pode ser identificado por um URI, use 200 (OK) ou 204 (Sem conteúdo).
• Se o recurso (após certa validação) for considerado como já existente, retorne 409 (Conflito)
• É sugerido usar o método POST para coleta e retornar 405 (Método não permitido) em um único recurso

O resultado para este método não pode ser armazenado em cache. Precisamos incluir o cabeçalho Cache-Control ou Expires se quisermos usar o cache para o método POST. Em relação a GET com resultado em cache, POST (e PUT, PATCH e DELETE) deve invalidar o cache.

O método addBook (…) é anotado com @PostMapping , mapeando solicitações HTTP POST em métodos de tratamento específicos. Após a criação bem-sucedida de um recurso, o código de resposta HTTP 201 (criado) é retornado com informações do livro no corpo da resposta (que inclui o novo id gerado para este recurso), com ‘Local’ definido no cabeçalho.

Exemplo curl

curl -X DELETE "http://localhost:8080/spring-rest-examples/rest/v1/books/2" -H "accept: */*"

Corpo da resposta — 201 (criado)

{
  "id": 11,
  "oclc": "23033258",
  "isbn10": nulo,
  "isbn13": nulo,
  "title": "Mero Cristianismo"
}

Cabeçalhos de resposta

cache-control: no-cache, no-store, max-age = 0, must-revalidate 
content-type: application / json; charset = UTF-8 
data: quinta-feira, 12 de setembro de 2019, 15:29:32 GMT 
expira em: 0 
localização: / rest / v1 / books / 11 
pragma: no-cache 
transfer-encoding: chunked 
x-content-type-options: nosniff 
x-frame-options: DENY 
proteção x-xss: 1; modo = bloco

PUT

O método PUT é usado para atualizar o recurso existente. O método PUT é idempotente, o cliente pode enviar a mesma solicitação várias vezes e terá o mesmo resultado que enviar uma vez.

• Em caso de atualização bem-sucedida, use o código de resposta HTTP 200 (OK) ou 204 (Sem conteúdo). 204 (Sem conteúdo) normalmente é usado se a ação foi executada, mas a resposta não inclui uma entidade (aplicada também para PATCH e DELETE). Pessoalmente, escolho 200 (OK), indicando uma atualização bem-sucedida.
• Caso o recurso não exista, crie um novo recurso ou rejeite a solicitação PUT pelo retorno 404 (Não Encontrado). Pessoalmente, opto por retornar 404 (não encontrado), já que o método HTTP POST mais adequado é usado para criar um novo recurso — tente torná-lo consistente.
• Se um novo recurso for criado por solicitação PUT, a resposta deve ser 201 (Criado)

Se PUT tentar modificar os recursos em cache, o cache deve ser invalidado. As respostas a este método não podem ser armazenadas em cache .

O método updateBook (…) é anotado com @PutMapping . Após a atualização bem-sucedida, o código de resposta HTTP 200 (OK) é retornado. Se o URL fornecido não representar nenhum recurso existente, então 404 (não encontrado).

Curl PUT

curl -X PUT "http://localhost:8080/spring-rest-examples/rest/v1/books/1" -H "accept: */*" -H "Content-Type: application/json" -d "{ \"id\": 1, \"oclc\": 1827184, \"isbn10\": null, \"isbn13\": null, \"title\": \"The Hobbit - There and Back Again\" },"

A diferença entre POST e PUT pode ser declarada da seguinte forma: Os pedidos POST são feitos em coleções de recursos, enquanto os pedidos PUT são feitos em um único recurso.

A solicitação PUT é usada para substituir completamente o recurso no URL fornecido com os dados fornecidos (atualização COMPLETA). Para atualização PARCIAL, usamos o método PATCH.

PATCH

As solicitações PATCH são usadas para fazer atualizações parciais em um recurso.

• Em caso de atualização bem-sucedida, use o código de resposta HTTP 200 (OK) ou 204 (Sem conteúdo). Da mesma forma que PUT, eu escolho 200 (OK) indicando uma atualização bem-sucedida.
• Caso o recurso não exista, retorne 404 (Não Encontrado). Evite a criação de novos recursos com base em dados / informações parciais.

Se o PATCH tentar modificar os recursos em cache, o cache deve ser invalidado. As respostas a este método não podem ser armazenadas em cache . No meu exemplo abaixo, estou usando apenas String como minha carga útil para atualizar o título.

O método updateBookTitle (…) é anotado com @PatchMapping . Após a atualização bem-sucedida, o código de resposta HTTP 200 (OK) é retornado. Se o URL fornecido não representar nenhum recurso existente, então 404 (não encontrado).

Exemplo curl

curl -X PATCH "http://localhost:8080/spring-rest-examples/rest/v1/books/1" -H "accept: */*" -H "Content-Type: application/json" -d "The Hobbit"

DELETE

O método DELETE é usado para excluir um recurso identificado pelo URI de solicitação.

• Uma exclusão bem-sucedida deve retornar o código de resposta HTTP 200 (OK) ou 204 (Sem conteúdo). DELETE pode ser uma solicitação de longa execução ou assíncrona, portanto, retorne 202 (Aceito) se a ação tiver sido enfileirada.
• Caso o recurso não exista retornar 404 (não encontrado)

As operações DELETE são idempotentes . Se você EXCLUIR um recurso, ele é removido da coleção. Embora chamar DELETE em um recurso na hora subsequente retorne um 404 (não encontrado), o recurso ainda (ou já) foi removido da coleção.

Se DELETE tentar excluir um recurso armazenado em cache, o cache deverá ser invalidado. As respostas a este método não podem ser armazenadas em cache .

O método deleteBookById (…) é anotado com @DeleteMapping . Após a exclusão bem-sucedida, o código de resposta HTTP 200 (OK) é retornado. Se o URL fornecido não representar nenhum recurso existente, então 404 (não encontrado).

Exemplo curl

curl -X DELETE "http://localhost:8080/spring-rest-examples/rest/v1/books/2" -H "accept: */*"

Notas

Obrigado por chegar ate aqui
Você pode substituir @GetMapping, @PostMapping, @PutMapping, @PatchMapping, @DeleteMapping por @RequestMapping com o parâmetro de método especificado.

Métodos seguros: métodos HTTP que não modificam recursos, ou para ser mais preciso: não mudam a representação do resultado. Ainda é possível que métodos seguros mudem coisas em um servidor ou recurso, mas isso não deve refletir em uma representação diferente. Métodos seguros podem ser armazenados em cache, pré-buscados sem nenhuma repercussão para o recurso

Métodos idempotentes : métodos HTTP que podem ser chamados muitas vezes sem resultados diferentes. Não importa se o método é chamado apenas uma vez ou várias vezes, o resultado deve ser o mesmo. Novamente, isso se aplica apenas à representação do resultado, não ao próprio recurso.