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.

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.