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. PEGAR

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

     Copiar código

     GET /usuarios GET /usuarios/123

2. PUBLICAR

   • 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 :
     festança

     Copiar código

     POST /usuarios
     Corpo da Requisição :
     json

     Copiar código

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

3. COLOCAR

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

     Copiar código

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

     Copiar código

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

4. CORREÇÃO

   • 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 :
     festança

     Copiar código

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

     Copiar código

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

5. EXCLUIR

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

     Copiar código

     DELETE /usuarios/123

6. OPÇÕES

   • 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 :
     festança

     Copiar código

     OPTIONS /usuarios

7. CABEÇA

   • Descrição : Recuperar os cabeçalhos de resposta de um recurso sem o corpo.
   • Uso : Verifique metadados ou existência de um recurso.
   • Idempotente : Sim.
   • Exemplo :
     festança

     Copiar código

     HEAD /usuarios/123

Idempotência e Segurança dos Verbos

• Idempotente : Uma operação que pode ser realizada várias 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 : Retorna códigos de status adequados para indicar o resultado das operações:

   • 200 OK : Requisição bem-sucedida.
   • 201 Criado : 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 Não autorizado : Autenticação necessária.
   • 403 Proibido : Acesso negado.
   • 404 Not Found : recurso não encontrado.
   • 500 Erro interno do servidor : 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 : Crie 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 :
  festança

  Copiar código

  POST /pedidos
  Corpo :
  json

  Copiar código

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

    Copiar código

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

2. Obter Detalhes de um Pedido

• Requisição :
  festança

  Copiar código

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

    Copiar código

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

3. Atualizar um Pedido

• Requisição :
  festança

  Copiar código

  PUT /pedidos/789
  Corpo :
  json

  Copiar código

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

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

• Requisição :
  festança

  Copiar código

  PATCH /pedidos/789
  Corpo :
  json

  Copiar código

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

5. Excluir um Pedido

• Requisição :
  festança

  Copiar código

  DELETE /pedidos/789
• Resposta :
  • Status : 204 Sem conteúdo

Considerações Adicionais

• Versionamento da API : Inclui 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

• Hipermídia como mecanismo de estado de aplicação (HATEOAS) : Inclui links na resposta para facilitar a navegação pelos recursos.

  Exemplo de resposta com HATEOAS :

  json

  Copiar código

  { "id" : 123 , "nome" : "João Silva" , "e-mail" : "joao@example.com" , "links" : [ { "rel" : "self" , "href" : "/usuários/123" } , { "rel" : "pedidos" , "href" : "/usuarios/123/pedidos" } ] }

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

  • Exemplo :
    festança

    Copiar código

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

Conclusão

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

---

Quer otimizar suas habilidades em software? Visite askpedromartins.com​ para aconselhamento especializado e soluções adaptadas às suas necessidades de desenvolvimento.