Curso de design de APIs REST

2019-07-27 06:34:46 https://pt.m.wikipedia.org/wiki/Lista_de_c%C3%B3digos_de_estado_HTTP Aberto / Como

2019-07-18 21:02:19 pronto, terminamos nosso curso de design de API REST, agora você pode implementar no seu servidor e ter as melhores práticas. E confere lá @AcervoHackerBR, iremos postar um livro sobre clean code, para o seu código ficar ainda mais bonito e organizado. :D Aberto / Como

2019-07-18 21:00:32 14 - Design URI para pesquisa
Se sua API estiver fornecendo uma pesquisa, você precisará criar um sistema robusto para lidar com todos os tipos de consultas de pesquisa. No caso de pesquisas simples, a consulta poderia ser simplesmente:

http://api.example.com/users/?q=male

Mas, no caso de pesquisas complexas, você precisa considerar os URIs de pesquisa global e com escopo definido para lidar com a pesquisa corretamente. Se você deseja fazer uma pesquisa global em todos os seus recursos, o modelo a seguir é recomendado, em que q indica a consulta.

http://api.example.com/search?q=new+web+codes

No caso de uma pesquisa específica em um recurso, você deve prefixar com a consulta de pesquisa.

http://api.example.com/users?q=pending+lessons

Nota: Deixamos cair o "/search" explícito no URI e estamos contando com o parâmetro? Q para indicar a consulta com escopo definido. Aberto / Como

2019-07-18 20:42:45 13 - Paginação e Resposta Parcial

A ideia aqui não é retornar todos os recursos no banco de dados. Sua API deve ter agilidade suficiente para permitir que o usuário personalize a solicitação com parâmetros opcionais para obter exatamente o que precisa, tanto em termos de tipos quanto de quantidade.

Isso é especialmente importante em aplicativos para dispositivos móveis, em que a largura de banda e os recursos são limitados.

Resposta Parcial
Para fazer uma consulta, use somente parâmetros especificados, use campos de consulta opcionais. Usar uma lista de campos delimitada por vírgulas é comum. Por exemplo, vamos criar uma consulta que leve apenas o nome do usuário, o status e o avatar.

http://api.example.com/users?fields=name,status,avatar

Nesse caso, ele retorna apenas 3 parâmetros da coleção do usuário. No entanto, na ausência dos campos, ele pode retornar mais de 100 parâmetros, o que é desnecessário para nós se apenas listarmos todos os usuários.

Paginação
Imagine que você queira buscar um recurso de coleção que tenha mais de um milhão de entradas. Não é uma boa idéia buscar todas de uma vez, pois o usuário pode ver apenas 10 a 20 entradas em seus dispositivos. Paginação pode resolver este problema.
Existem dois parâmetros para isso: deslocamento e limite.
- offset identifica de qual entrada a busca deve começar
- limit identifica quantas entradas devem ser retornadas, a partir do deslocamento

Então, para obter 20 entradas por solicitação, a consulta deve ser como:

http://api.example.com/users?offset=0&limit=20
http://api.example.com/users?offset=20&limit=20
...

Nota: É uma boa prática definir um limite e um deslocamento padrão para seus URIs de coleta, portanto, se o limite e o deslocamento não forem especificados, não haverá uma carga pesada no servidor. Por exemplo, você pode definir o limite padrão como 10 e definir o deslocamento como 0. Aberto / Como

2019-07-14 21:26:22 12 - Versionamento da API
Antes de liberar sua API REST, considere também como lidar com o controle de versão, porque você não pode garantir que todos os seus usuários sempre usarão a versão mais recente da API.

Por exemplo, imagine que você publicou um aplicativo na loja de aplicativos com uma API (v1). Na próxima versão da sua API (v2), que será usada em seu site, você alterou uma das chamadas de URI e o formato de resposta. Portanto, se você não oferecer suporte a versões, seu aplicativo falhará até você atualizar seu aplicativo com a nova versão da API.

Agora que você sabe o motivo por trás do controle de versão, vamos ver como isso deve ser feito.
A maneira mais comum de criar uma versão de uma API é incluir o número da versão em cada URL. Por exemplo:

http://api.example.com/v1/users/
http://api.example.com/v2.1/users/{id}/projects/{id}/run

Desta forma, a estrutura e a versão estão corretas no URI, e é simples de usar.

A outra abordagem é incluir a versão no cabeçalho HTTP. Se você usar essa abordagem, ainda poderá manipular a solicitação em que a versão está ausente e não está visível no próprio URI.

Nota: Existem outros tipos de abordagens em que o controle de versão é opcional e, se uma versão não for especificada, ela obterá automaticamente a versão mais recente. A desvantagem dessas abordagens é que os desenvolvedores devem agir imediatamente para atualizar os aplicativos, a fim de não quebrar a experiência.

Outra maneira de atualizar sua API é manipular cada plataforma separadamente. Digamos que você tenha aplicativos para Android, iOS e Web, e eles se comportam de maneira diferente. Você pode criar versões diferentes para sua API para otimizar cada plataforma separadamente:

http://api.example.com/a-v5/codes/{id}
http://api.example.com/i-v4/codes/{id}
http://api.example.com/w-v16/codes/{id}

Nota: O gerenciamento de plataformas geralmente é tratado usando os cabeçalhos HTTP. Aberto / Como

2019-07-14 21:20:53 11 - Deletando uma operação (DELETE)
A operação DELETE é usada para excluir um recurso identificado por um URI.

Na exclusão bem-sucedida, retorne o status HTTP 200 (OK), junto com um corpo de resposta, talvez a representação do item excluído (geralmente exige muita largura de banda) ou uma resposta agrupada. Como alternativa, retorne o status HTTP 204 (NO CONTENT) sem nenhum corpo de resposta.

As operações DELETE são idempotentes. Se você excluir um recurso, ele será removido.
Chamar repetidamente DELETE nesse recurso é o mesmo: o recurso desapareceu.
Por exemplo, se chamar DELETE diminui um contador (dentro do recurso), a chamada DELETE não é mais idempotente. As estatísticas e medições de uso podem ser atualizadas enquanto ainda considera o serviço idempotente, desde que nenhum dado de recurso seja alterado. Recomenda-se o uso de POST para solicitações de recursos não idempotentes.

Exemplos:

DELETE https://www.example.com/users/11111
DELETE http://www.example.com/users/11111/posts/222

Nota: Chamar DELETE em um recurso uma segunda vez geralmente retornará um 404 (NOT FOUND), pois ele já foi removido e, portanto, não está mais disponível.
Isso, por algumas opiniões, torna as operações DELETE não mais idempotentes; no entanto, o estado final do recurso é o mesmo.
Retornar um 404 é aceitável e comunica com precisão o status da chamada. Aberto / Como

2019-07-14 21:17:23 10 - Atualizando uma operação (PUT)
As APIs PUT são usadas principalmente para atualizar um recurso existente (se o recurso não existir, a API pode decidir criar um novo recurso ou não).

Se um novo recurso tiver sido criado pela API PUT, o servidor deverá informar o agente do usuário por meio do código de resposta HTTP 201 (Criado) e, se um recurso existente for modificado, a resposta 200 (OK) ou 204 (Sem Conteúdo) código deve ser enviado para indicar a conclusão bem-sucedida da solicitação.

Se a solicitação passar por um cache e o URI de solicitação identificar uma ou mais entidades armazenadas no cache, essas entradas deverão ser tratadas como obsoletas. As respostas a esse método não podem ser armazenadas em cache.

Exemplos:

HTTP PUT http://www.appdomain.com/users/48848
HTTP PUT http://www.appdomain.com/users/48848/accounts/2744

Nota: A diferença entre as APIs POST e PUT pode ser observada em URIs de solicitação: solicitações POST são feitas de coleções de recursos, enquanto as solicitações PUT são feitas no recurso individual. Aberto / Como

2019-07-14 21:14:24 9 - Criando uma operação (POST)
A operação POST é usada para criar novos recursos subordinados.

Em termos de REST, os métodos POST são usados para criar um novo recurso na coleção de recursos.
A transmissão de dados junto com a solicitação POST é feita usando o corpo da mensagem HTTP.

Idealmente, se um recurso tiver sido criado no servidor de origem, a resposta deverá ser o código de resposta HTTP 201 (Criado) e conter uma entidade que descreva o status da solicitação e faça referência ao novo recurso.

Muitas vezes, a ação executada pelo método POST pode não resultar em um recurso que possa ser identificado por um URI. Nesse caso, o código de resposta HTTP 200 (OK) ou 204 (Sem conteúdo) é um status de resposta apropriado.

As respostas a esse método não podem ser armazenadas em cache, a menos que a resposta inclua campos apropriados de cabeçalho Cache-Control ou Expires.

Por exemplo, uma solicitação POST para o endpoint da API a seguir cria um novo "item" na coleção "items". Parâmetros adicionais são passados junto com o corpo da mensagem.

http://example.com/items

Nota: O método POST não é seguro nem idempotente, e invocar duas solicitações POST idênticas resultará em dois recursos diferentes contendo as mesmas informações (exceto os IDs de recurso). Aberto / Como

2019-07-14 21:09:06 8 - Operação de leitura (GET)
As solicitações GET são usadas para recuperar somente informações / representação de recursos, não para editá-las de qualquer forma.
Como as solicitações GET não alteram o estado do recurso, essas solicitações são conhecidas como métodos seguros. Além disso, as APIs GET devem ser idempotentes, o que significa que fazer várias solicitações idênticas deve produzir o mesmo resultado toda vez que outra API (POST ou PUT) alterar o estado do recurso no servidor.

Para qualquer solicitação HTTP GET, se um recurso for encontrado no servidor, ele deve retornar o código de resposta HTTP 200 (OK) - juntamente com o corpo da resposta, que geralmente é XML ou JSON (devido à natureza independente de plataforma).

Caso um recurso NÃO seja encontrado no servidor, ele deve retornar o código de resposta HTTP 404 (NOT FOUND).
Da mesma forma, se for determinado que a solicitação GET em si não está formada corretamente, o servidor retornará o código de resposta HTTP 400 (BAD REQUEST).

Exemplos:

GET http://www.test.com/posts
GET http://www.test.com/posts/36273

Nota: Se o URI do Pedido fizer referência a um processo de produção de dados, serão os dados produzidos retornados como a entidade na resposta e não o texto de origem do processo, a menos que esse texto seja a saída do processo. Aberto / Como

2019-07-14 21:05:14 7 - Consistência de nomes

Existem algumas regras mais gerais que ajudarão você a manter sua API REST consistente e sustentável. Sempre use barra (/) para separar as partes do caminho O caractere de barra invertida define o relacionamento hierárquico entre os recursos.

http://api.example.com/users/{id}/posts

Nunca use barra final (/) Barras à direita não fazem nada e podem ser confusas. É melhor deixá-los completamente.

http://api.example.com/users/{id}/posts/ /*Bad*/
http://api.example.com/users/{id}/posts /*Good*/

Hífens (-) são boas escolhas para separar palavras Os hífens ajudam os usuários a digitalizar e ler mais rapidamente, especialmente em nomes longos de URI.

http://api.example.com/users/accessLevels /*Bad*/ http://api.example.com/users/access-levels /*Good*/

É possível usar sublinhados em vez de hífens, mas em alguns casos (com base na fonte do sistema) eles não são claramente visíveis e não são aceitáveis em URIs.

Sempre use letras minúsculas
O uso de letras minúsculas nos caminhos URI é sempre preferencial. No entanto, o componente host pode estar em letras maiúsculas.

http://api.example.org/home/my-file
HTTP://API.EXAMPLE.ORG/home/my-file
http://api.example.org/Home/My-File

No exemplo acima, todos os três são a mesma API, mas o terceiro pode causar problemas com base na implementação e no tipo do servidor.

Nunca use extensões de arquivo
Eles parecem ruins em URIs e os tornam mais longos.
Use outros métodos para determinar o tipo de arquivo; não confie na extensão.

http://api.example.com/files/license.pdf /*Bad*/
http://api.example.com/files/license /*Good*/

Sempre use o componente de consulta para filtrar a coleção de URI
Use os componentes de consulta (?, &) Para classificar, paginar ou fornecer outros parâmetros ao seu URI. Nunca crie um novo URI para conseguir isso.

http://api.example.com/projects/{id}/run?lang=cpp
http://api.example.com/projects/{id}/run?lang=cpp&type=gcc

Nunca use nomes de função CRUD
Nada no URI deve indicar qual ação está sendo executada.
 
GET http://api.example.com/users/ //pega todos os usuários
POST http://api.example.com/users/ //Cria um novo usuário
GET http://api.example.com/users/{id} // pega o id do usuário
PUT http://api.example.com/users/{id} // Atualiza o user com id
DELETE http://api.example.com/users/{id} //Deleta o usuário com o id

Nota: Você é livre para criar e seguir novas regras, desde que mantenham seus URIs simples, legíveis, fáceis de manter e uniformes. Aberto / Como