Standard Methods

Os “Standard Methods” em Web APIs são um conjunto de métodos HTTP padrão que definem como os clientes interagem com os recursos de uma API.

Uma forma de construir uma API previsível é variar apenas o recurso disponível e mantendo consistente o conjunto de ações específicas (i.e. métodos) que podem ser aplicados a todos os recursos.

Cada método tem um propósito específico e é usado para realizar diferentes tipos de operações em recursos. Vamos explorar cada um deles com base nas informações dos documentos em meu conhecimento:

1. GET

• Objetivo: Usado para recuperar informações de um recurso específico.
• Quando Usar: Sempre que precisar obter dados sem modificar o estado do recurso.
• Exemplo: GET /users/123 - Retorna informações do usuário com ID 123.

LIST

Certamente! Vamos falar sobre o método LIST em Web APIs, com base nas informações dos documentos em meu conhecimento:

• Objetivo: O método LIST é usado para listar recursos em uma coleção. Por exemplo, um GET para o endpoint /books em uma API de biblioteca retornaria uma lista de todos os livros disponíveis.
• Idempotência: Assim como o método GET, o LIST é idempotente. Isso significa que várias chamadas ao mesmo endpoint sob as mesmas condições devem retornar o mesmo conjunto de recursos, desde que não haja alterações no estado dos recursos entre as chamadas.
• Acesso Controlado: Se um usuário solicita uma lista de recursos, mas não tem acesso a todos eles, a API geralmente retornará apenas os recursos aos quais o usuário tem acesso. Isso é feito em vez de negar completamente o acesso à lista.
• Resultados Paginados: Para coleções grandes, o LIST pode retornar resultados paginados para evitar sobrecarregar o cliente e o servidor. Isso significa que a resposta pode incluir um subconjunto de todos os recursos disponíveis, juntamente com informações para recuperar o próximo conjunto de resultados.
• Filtros e Parâmetros: O método LIST frequentemente suporta filtros e outros parâmetros na query string para permitir que os usuários refinem a lista de recursos retornados. Por exemplo, /books?author=Rowling poderia listar apenas livros escritos por J.K. Rowling.
• Não Envolvimento de Corpo de Requisição: Em geral, o LIST (como o GET) não utiliza um corpo de requisição. Todos os parâmetros necessários são fornecidos na URL ou como cabeçalhos de requisição.
• Performance e Eficiência: Deve-se considerar a eficiência ao implementar o método LIST, especialmente para coleções muito grandes, para evitar problemas de desempenho tanto no servidor quanto no cliente.
• Consistência: É importante manter uma abordagem consistente na forma como o LIST é implementado em diferentes partes da API para garantir uma experiência de usuário coesa e intuitiva.

2. POST

• Objetivo: Utilizado para criar um novo recurso ou submeter dados a um recurso para processamento.
• Quando Usar: Para criar novos recursos ou quando a operação tem efeitos colaterais (como submeter um formulário).
• Sempre retorna o novo recurso criado.
• O id do novo recurso deve ser quase sempre gerado pelo servidor. Apenas em situações raras (como sicronização de trabalho offline), que o id deve ser gerado pelo client.
• Exemplo: POST /users com dados do usuário no corpo da requisição para criar um novo usuário.

3. PUT

• Objetivo: Usado para atualizar um recurso existente ou criar um recurso em um URI específico.
• Quando Usar: Quando precisar atualizar um recurso inteiro ou criar um recurso com um identificador conhecido.
• Exemplo: PUT /users/123 com dados atualizados do usuário para atualizar o usuário com ID 123.

4. DELETE

• Objetivo: Remove um recurso especificado.
• Quando Usar: Quando precisar excluir um recurso.
• Retorna void (no content)
• Exemplo: DELETE /users/123 - Exclui o usuário com ID 123.

Semântica Declarativa (indempotente) vs. Semântica Imperativa (não indempotente)

Isso se verifica quando o DELETE é chamado mais de uma vez para o mesmo recurso. O que se pretende? dizer que o recurso não deve existir ou remover o recurso?

• Quando se pretende uma semântica declarativa (indempotente), o response deve ser 200 OK.
• Quando se pretende uma semântica imperativa, o response deve ser 404 NOT FOUND, afinal o recurso já foi apagado. Esse é o mais comum, mas não há indepomtência.

5. PATCH

• Objetivo: Usado para aplicar atualizações parciais a um recurso.
• Quando Usar: Para atualizações que não substituem todo o recurso, mas apenas uma parte dele.
• Exemplo: PATCH /users/123 com uma alteração de nome para atualizar parcialmente o usuário com ID 123.

6. OPTIONS

• Objetivo: Retorna os métodos HTTP suportados pelo servidor para um recurso específico.
• Quando Usar: Para descobrir quais operações são suportadas em um recurso.
• Exemplo: OPTIONS /users/123 - Retorna os métodos suportados para o usuário com ID 123.

7. HEAD

• Objetivo: Semelhante ao GET, mas retorna apenas os cabeçalhos da resposta sem o corpo.
• Quando Usar: Quando precisar das metainformações de um recurso sem o corpo da resposta.
• Exemplo: HEAD /users/123 - Retorna os cabeçalhos da resposta para o usuário com ID 123.

Cada um desses métodos é projetado para garantir uma interação padronizada com a Web API, seguindo os princípios do protocolo HTTP. Essa padronização facilita o desenvolvimento de APIs consistentes e fáceis de usar, além de permitir que os clientes interajam de maneira previsível com os recursos da API.

Implementação

Não é obrigatório implementar todos os métodos HTTP padrão (Standard Methods) para cada recurso em uma Web API. A implementação desses métodos deve ser baseada nas necessidades específicas e na funcionalidade do recurso. Aqui estão algumas considerações:

1. Relevância Funcional:

   • Cada método padrão tem uma função específica (como recuperação, atualização, criação ou exclusão de recursos).
   • Um recurso deve implementar apenas os métodos que fazem sentido para suas operações. Por exemplo, se um recurso é somente para leitura, pode não ser necessário implementar os métodos POST, PUT, DELETE e PATCH.

2. Segurança e Controle:

   • Implementar todos os métodos para um recurso pode introduzir riscos de segurança se não forem necessários.
   • Por exemplo, expor um método DELETE em um recurso que nunca deve ser excluído pode levar a exclusões acidentais ou mal-intencionadas.

3. Código de Status HTTP:

   • Se um cliente tenta usar um método não suportado em um recurso, a API deve responder com o código de status HTTP 405 (Method Not Allowed).

4. Simplicidade e Manutenção:

   • Implementar apenas os métodos necessários mantém a API simples e focada.
   • Isso facilita a manutenção e compreensão da API, tanto para os desenvolvedores quanto para os usuários.

Em resumo, a escolha de quais métodos padrão implementar para um recurso específico deve ser guiada pela funcionalidade desse recurso, considerações de segurança e as melhores práticas de design de API.

Side Effects

Dizer que os métodos padrão (Standard Methods) em uma Web API não devem ter efeitos colaterais (side effects) significa que a execução desses métodos não deve alterar o estado do sistema de maneira inesperada ou indesejada. Aqui estão alguns pontos para entender melhor esse conceito:

1. Idempotência:

   • Métodos como GET, PUT, DELETE, e PATCH são considerados idempotentes. Isso significa que, independentemente de quantas vezes a operação é repetida sob as mesmas condições, o estado final do recurso será o mesmo.
   • Por exemplo, a execução repetida de um método DELETE no mesmo recurso deve resultar no mesmo estado final (recurso excluído), sem efeitos colaterais adicionais após a primeira chamada.

2. Previsibilidade:

   • Os métodos devem ter um comportamento previsível, sem causar mudanças não documentadas ou inesperadas no estado dos recursos ou no sistema como um todo.
   • Por exemplo, um ==método GET não deve modificar o recurso== que está sendo acessado, pois sua função é apenas recuperar dados.

3. Segurança:

   • Evitar efeitos colaterais ajuda a manter a segurança e a integridade dos dados. Uma API onde os métodos agem de forma previsível e consistente é menos propensa a erros e vulnerabilidades.

4. Consistência com a Semântica HTTP:

   • O protocolo HTTP define a ação esperada para cada método. Manter-se fiel a essas definições ajuda a criar uma API que se comporta de maneira consistente com as expectativas dos desenvolvedores e usuários.

5. Exceções: -Alguns métodos, como ==POST, podem ter efeitos colaterais por natureza, pois são usados para criar ou alterar recursos==. Nesses casos, os efeitos colaterais são parte da operação pretendida.

Em resumo, evitar efeitos colaterais nos métodos padrão de uma Web API é crucial para manter a consistência, previsibilidade e segurança da API. Isso permite que os usuários da API entendam claramente o que cada chamada vai fazer, sem surpresas indesejadas.