Histórico da Página

Padrão de nomenclatura 

http://{{host}}/api/{{agrupador}}/{{versão}}/{{resource}}

• Dê preferência para o plural ao disponibilizar o resource. Utilize /users ao invés de /user;
• Dê preferência para URL's em minúsculo, evite GET /Users, use GET /users;
• Na API, utilizamos semantic versioning, um padrão que é dividido em major, minor e patch. Somente a Major Version é utilizada na URL. Por exemplo: V1 ou V2; 
• Deve ser orientada a recursos representados por substantivos no plural. Não se deve orientar a verbos Get, Put, Post e Delete.

A raiz do resource deve retornar uma coleção. Por exemplo /users deve retornar um lista de usuários.
Se desejar obter um resource especifico utilize o nível seguinte especificando seu identificador único. GET /users/2. Não precisa ser o id do banco, poderia ser outro campo, desde que seja identificador único. Um usuário poderia ser o username.

• GET /users -> Retorna uma lista de usuários
• GET /users/bruno -> Retorna o usuário com username bruno
• POST /users -> Cria um usuário
• PUT /users/bruno -> Atualiza o usuário bruno
• PATCH /users/bruno -> Atualiza parcialmente o usuário bruno
• DELETE /users/bruno -> Remove o usuário bruno

Relacionamento filho - Se existir alguma tabela filho do resource, eles devem estar mapeados para o mesmo endpoint. Exemplo

• GET /users/bruno/claims -> Retorna uma lista de claims do usuário bruno
• GET /users/bruno/claims/6 -> Retorna o claims com Id 6
• POST /users/bruno/claims -> Cria uma claim para usuário bruno
• PUT /users/bruno/claims/6 -> Atualiza a claim 6 do usuário bruno
• PATCH /users/bruno/claims/6 -> Atualiza parcialmente a claim 6 do usuário bruno
• DELETE /users/bruno/claims/6 -> Remove a claim 6 do usuário bruno

Evite adicionar na URI a operação a ser realizada no recurso

Os recursos que uma aplicação gerencia podem ser manipulados de diversas maneiras, sendo para isso disponibilizada algumas operações para manipula-los, tais como: criar, listar, excluir, atualizar, etc.

A manipulação dos recursos deve ser feita utilizando-se os métodos do protocolo HTTP, que inclusive é um dos princípios do REST que será discutido mais adiante.

Portanto, evite definir URIs que contenham a operação a ser realizada em um recurso, tais como:

• GET/PUT/DELETE/PATCH /users/Cadastrar;
• GET/PUT/DELETE/PATCH /users/bruno/Excluir;
• GET/PUT/DELETE/PATCH /users/bruno/Atualizar.

Logo ações se fazem necessários no dia-a-dia. E é importante reforçar que não fere os padrões REST.

• POST /candidatos/{id}/candidatar -- Grava a aplicação de um candidato a uma vaga
• POST /candidatos/{id}/aprovar -- Aprova um candidato
• DELETE /candidatos/{id}/aprovar -- Cancela a aprovação
• POST /candidatos/{id}/reprovar -- Reprova o candidato
• DELETE /candidatos/{id}/reprovar -- Cancela a reprovação
• POST /candidatos/{id}/transferir -- Transfere o candidato para outra vaga
• DELETE /candidatos/{id}/transferir -- Cancela a transferência

Nesse formato a comunicação é clara. No backend o desenvolvedor não vai precisar criar if's ou switchs e traduzir a intenção do método "CRUD". O próprio endpoint comunica sua intenção.

Os recursos gerenciados por uma aplicação, e identificados unicamente por meio de sua URI, geralmente podem ser manipulados de diversas maneiras. É possível criá-los, atualizá-los, excluí-los, dentre outras operações.

Quando um cliente dispara uma requisição HTTP para um serviço, além da URI que identifica quais recursos ele pretende manipular, é necessário que ele também informe o tipo de manipulação que deseja realizar no recurso. É justamente aí que entra um outro conceito da Web, que são os métodos do protocolo HTTP.

O protocolo HTTP possui diversos métodos, sendo que cada um possui uma semântica distinta, e devem ser utilizados para indicar o tipo de manipulação a ser realizada em um determinado recurso.

Vejamos agora os principais métodos do protocolo HTTP e o cenário de utilização de cada um deles:

• GET: Obter os dados de um recurso.

• POST: Criar um novo recurso.

• PUT: Substituir os dados de um determinado recurso.

• PATCH: Atualizar parcialmente um determinado recurso.

• DELETE: Excluir um determinado recurso.

• HEAD: Similar ao GET, mas utilizado apenas para se obter os cabeçalhos de resposta, sem os dados em si.

• OPTIONS: Obter quais manipulações podem ser realizadas em um determinado recurso.

Geralmente as aplicações apenas utilizam os métodos GET, POST, PUT e DELETE, mas se fizer sentido em sua aplicação utilizar algum dos outros métodos, não há nenhum problema nisso.

Idempotente significa que o endpoint pode ser chamado várias vezes sem resultados diferentes. Não importa se o método é chamado apenas uma ou dez vezes. O resultado deve sempre o mesmo. Isso se aplica apenas ao resultado, não ao próprio recurso.

Safe são métodos Read-only. Isso significa que são seguros e não importa quantas vezes chamar, ele não irá alterar o estado do resource.

Quando o servidor recebe uma solicitação HTTP, o cliente deve saber o resultado da ação. Se houve sucesso ou falhou. Os códigos de status HTTP são vários códigos padronizados, com várias explicações em vários cenários. O servidor sempre deve retornar o código de status correto.

A seguir estão as categorias dos códigos HTTP:

• 2xx - Status de sucesso
• 3xx - Categoria de redirecionamento
• 4xx - Erro no Cliente
• 5xx - Erro no server

2xx - Sucesso

Abaixo uma tabela de quando utilizar cada um dos Status Code.

• 200 Ok - Padrão que representa sucesso. Resposta padrão para GET, quando há resultados.
• 201 Created - Indica que um recurso foi criado. Utilize para a resposta do POST. E também retorne o Header Location indicando o GET dessa informação.
• 204 No Content - Representa que a request foi processada com sucesso, mas não há conteúdo para ser retornado. Utilize para PUT, PATCH e DELETE. E também para situações em que o GET não retornou resultados.
• 202 Accepted - Indica que o servidor aceitou a request. Esse é um ótimo Status para processos assíncronos. Por exemplo um cenário onde o usuário faz upload de uma planilha que será processada em background.

3xx - Redirect

Como desenvolvedor, não consigo visualizar cenários em que será utilizado o redirect a partir de uma API RESTFul.

Em geral o 302 é bastante utilizado em desenvolvimento Frontend, como Razor. E o 301 Moved Permanently é utilizado por sysadmins, para indicar que um site foi permanentemente redirecionado para um novo endereço.

4xx - Client error

Indica que o client cometeu uma falha na requisição.

• 400 Bad Request - A solicitação não foi processada, pois o servidor não entendeu o que o cliente está solicitando.
• 401 Unauthorized - Indica que o client não está autenticado e não tem autorização para acessar o recurso.
• 403 Forbidden - Indica que o Client está autenticado e a requisição é válida. Porém o client não tem permissão de acesso naquele recurso.
• 404 Not Found - indica que o recurso não foi localizado.

5xx - Erros no servidor

Os status 5xx há dois que merecem destaque. É o erro 500, houve uma falha no servidor e não conseguiu processar a requisição. E o erro 503 que vai botar o pessoal de infra para correr. Indica que o serviço está indisponível. Status comum quando o Webserver sobrecarrega de requisições e não consegue mais processar nenhuma requisição. O 503 é comum em cenários de ataques DDoS.

Image Added

O Open Api, anteriormente conhecido como Swagger, é hoje o padrão mais utilizado para documentar API's. No ASP.NET Core é muito fácil configurar. Ele disponibiliza mecanismos para testar sua API no Browser.