Verbos HTTP em APIs RESTful

Verbos HTTP em APIs RESTful

As APIs RESTful utilizam os verbos HTTP para definir as ações que serão executadas sobre os recursos disponibilizados. Cada verbo representa uma operação específica e, quando combinado com uma URL, indica ao servidor o que o cliente deseja fazer com aquele recurso.

Principais Verbos HTTP

1. GET

   • Descrição: Recupera representações de recursos sem alterar o estado no servidor.
   • Uso: Obter dados ou listar recursos.
   • Idempotente: Sim (múltiplas requisições têm o mesmo efeito).
   • Exemplo:
     bash

     Copy code

     GET /usuarios GET /usuarios/123

2. POST

   • Descrição: Cria um novo recurso no servidor.
   • Uso: Enviar dados para serem processados, geralmente resultando na criação de um novo recurso.
   • Idempotente: Não (múltiplas requisições podem criar múltiplos recursos).
   • Exemplo:
     bash

     Copy code

     POST /usuarios
     Corpo da Requisição:
     json

     Copy code

     { "nome": "João Silva", "email": "joao@example.com" }

3. PUT

   • Descrição: Atualiza completamente um recurso existente ou cria um novo recurso se ele não existir.
   • Uso: Enviar uma representação completa do recurso para substituição.
   • Idempotente: Sim.
   • Exemplo:
     bash

     Copy code

     PUT /usuarios/123
     Corpo da Requisição:
     json

     Copy code

     { "nome": "João Silva", "email": "joao_novo@example.com" }

4. PATCH

   • Descrição: Atualiza parcialmente um recurso existente.
   • Uso: Enviar apenas as alterações para o recurso.
   • Idempotente: Não necessariamente (depende da implementação).
   • Exemplo:
     bash

     Copy code

     PATCH /usuarios/123
     Corpo da Requisição:
     json

     Copy code

     { "email": "joao_novo@example.com" }

5. DELETE

   • Descrição: Remove um recurso existente.
   • Uso: Excluir recursos.
   • Idempotente: Sim.
   • Exemplo:
     bash

     Copy code

     DELETE /usuarios/123

6. OPTIONS

   • Descrição: Retorna os métodos HTTP suportados para um recurso específico.
   • Uso: Descobrir as operações permitidas em um recurso.
   • Idempotente: Sim.
   • Exemplo:
     bash

     Copy code

     OPTIONS /usuarios

7. HEAD

   • Descrição: Recupera os cabeçalhos de resposta de um recurso sem o corpo.
   • Uso: Verificar metadados ou existência de um recurso.
   • Idempotente: Sim.
   • Exemplo:
     bash

     Copy code

     HEAD /usuarios/123

Idempotência e Segurança dos Verbos

• Idempotente: Uma operação que pode ser realizada múltiplas vezes sem alterar o resultado além da primeira aplicação.
• Seguros: Verbos que não alteram o estado do recurso no servidor (ex.: GET, HEAD).

Boas Práticas no Uso dos Verbos HTTP

1. Consistência Semântica: Utilize os verbos de acordo com suas definições para manter a clareza e a previsibilidade da API.

2. Uso Adequado do Status HTTP: Retorne códigos de status apropriados para indicar o resultado das operações:

   • 200 OK: Requisição bem-sucedida.
   • 201 Created: Recurso criado com sucesso (geralmente em resposta a um POST).
   • 204 No Content: Operação bem-sucedida, sem conteúdo no corpo da resposta (comum em DELETE).
   • 400 Bad Request: Requisição malformada.
   • 401 Unauthorized: Autenticação necessária.
   • 403 Forbidden: Acesso negado.
   • 404 Not Found: Recurso não encontrado.
   • 500 Internal Server Error: Erro no servidor.

3. Design de Recursos: Pense nos recursos como substantivos e nos verbos HTTP como ações sobre esses recursos.

   • Exemplo:
     • Recurso: usuarios
     • Ações:
       • GET /usuarios: Lista todos os usuários.
       • POST /usuarios: Cria um novo usuário.
       • GET /usuarios/123: Obtém informações do usuário com ID 123.
       • PUT /usuarios/123: Atualiza completamente o usuário 123.
       • PATCH /usuarios/123: Atualiza parcialmente o usuário 123.
       • DELETE /usuarios/123: Exclui o usuário 123.

4. Evite Verbos na URL: As ações são definidas pelo verbo HTTP, não pela URL.

   • Incorreto: /getUsuario, /deleteUsuario/123
   • Correto: GET /usuarios/123, DELETE /usuarios/123

Exemplo Prático: Gerenciando um Recurso "Pedidos"

1. Criar um Novo Pedido

• Requisição:
  bash

  Copy code

  POST /pedidos
  Corpo:
  json

  Copy code

  { "clienteId": 456, "itens": [ {"produtoId": 1, "quantidade": 2}, {"produtoId": 2, "quantidade": 1} ] }
• Resposta:
  • Status: 201 Created
  • Cabeçalho: Location: /pedidos/789
  • Corpo:
    json

    Copy code

    { "id": 789, "clienteId": 456, "itens": [...], "status": "novo" }

2. Obter Detalhes de um Pedido

• Requisição:
  bash

  Copy code

  GET /pedidos/789
• Resposta:
  • Status: 200 OK
  • Corpo:
    json

    Copy code

    { "id": 789, "clienteId": 456, "itens": [...], "status": "novo" }

3. Atualizar um Pedido

• Requisição:
  bash

  Copy code

  PUT /pedidos/789
  Corpo:
  json

  Copy code

  { "clienteId": 456, "itens": [ {"produtoId": 1, "quantidade": 3}, {"produtoId": 2, "quantidade": 1} ] }
• Resposta:
  • Status: 200 OK
  • Corpo: Representação atualizada do pedido.

4. Atualização Parcial (Status do Pedido)

• Requisição:
  bash

  Copy code

  PATCH /pedidos/789
  Corpo:
  json

  Copy code

  { "status": "enviado" }
• Resposta:
  • Status: 200 OK
  • Corpo: Pedido com o status atualizado.

5. Excluir um Pedido

• Requisição:
  bash

  Copy code

  DELETE /pedidos/789
• Resposta:
  • Status: 204 No Content

Considerações Adicionais

• Versionamento da API: Inclua a versão na URL ou nos cabeçalhos para gerenciar diferentes versões da API.

  • Exemplo: /v1/usuarios ou usando o cabeçalho Accept: application/vnd.example.v1+json

• Hypermedia as the Engine of Application State (HATEOAS): Inclua links na resposta para facilitar a navegação pelos recursos.

  Exemplo de Resposta com HATEOAS:

  json

  Copy code

  { "id": 123, "nome": "João Silva", "email": "joao@example.com", "links": [ {"rel": "self", "href": "/usuarios/123"}, {"rel": "pedidos", "href": "/usuarios/123/pedidos"} ] }

• Filtros e Paginação: Utilize parâmetros de query para filtrar e paginar resultados.

  • Exemplo:
    bash

    Copy code

    GET /usuarios?nome=joao&idade_min=18&pagina=2&limite=50

Conclusão

Compreender e utilizar corretamente os verbos HTTP em APIs RESTful é fundamental para construir interfaces web padronizadas, intuitivas e fáceis de manter. Seguindo essas práticas, você garante que sua API seja consistente e siga as convenções amplamente adotadas na indústria, facilitando a integração e o uso por desenvolvedores e clientes.

Looking to optimize your software skills? Visit askpedromartins.com for expert advice and solutions tailored to your development needs.