Diretrizes de Design da API RESTful – As melhores práticas

Facebook, Google, Github, Netflix e alguns outros gigantes da tecnologia deram uma chance aos desenvolvedores e produtos para consumir seus dados através de APIs e se tornaram uma plataforma para eles.
Mesmo que você não esteja escrevendo APIs para outros desenvolvedores e produtos, é sempre muito saudável para o seu aplicativo ter APIs lindamente criadas.

Há um longo debate na Internet, sobre as melhores maneiras de projetar as APIs e é uma das mais matizadas. Não há diretrizes oficiais definidas para o mesmo.

A API é uma interface, através da qual muitos desenvolvedores interagem com os dados. Uma boa API projetada é sempre muito fácil de usar e torna a vida do desenvolvedor muito suave. A API é a GUI para desenvolvedores, se é confusa ou não detalhada, então o desenvolvedor começará a encontrar as alternativas ou deixará de usá-la. A experiência dos desenvolvedores é a métrica mais importante para medir a qualidade das APIs.

A API é como um artista que se apresenta no palco e seus usuários são o público

1) Terminologias

Os seguintes são os termos mais importantes relacionados às APIs REST

  • O recurso é um objeto ou representação de algo, que possui alguns dados associados e pode haver um conjunto de métodos para operar sobre ele. Por exemplo, animais, escolas e funcionários são recursos e apagar, adicionar, atualizar são as operações a serem realizadas nesses recursos.
  • As coleções são conjuntos de recursos, por exemplo, as empresas são a coleção de recursos da empresa .
  • URL (Uniform Resource Locator) é um caminho através do qual um recurso pode ser localizado e algumas ações podem ser realizadas nele.

2) ponto final da API

Vamos escrever algumas APIs para empresas que tenham alguns Empregados, para entender mais.
/getAllEmployees é uma API que responderá com a lista de funcionários. Poucas APIs em torno de uma empresa se parecerão da seguinte maneira:

  • /addNewEmployee
  • /updateEmployee
  • /deleteEmployee
  • /deleteAllEmployees
  • /promoteEmployee
  • /promoteAllEmployees

E haverá toneladas de outros pontos de extremidade da API, como estes, para diferentes operações. Todos esses contêm muitas ações redundantes. Portanto, todos esses pontos finais da API seriam onerosos para manter, quando a contagem da API aumentar.

O que está errado?
O URL só deve conter recursos (substantivos) e não ações ou verbos. O caminho da API /addNewEmployee contém a ação addNew juntamente com o nome do recurso Employee .

Então, qual é a maneira correta?
/companies endpoint /companies é um bom exemplo, que não contém nenhuma ação. Mas a questão é como contamos ao servidor sobre as ações a serem realizadas no recurso das companies , a saber. quer para adicionar, excluir ou atualizar?

Aqui é onde os métodos HTTP (GET, POST, DELETE, PUT), também chamados de verbos, desempenham o papel.

O recurso deve ser sempre plural no ponto final da API e se quisermos acessar uma instância do recurso, sempre podemos passar o id na URL.

  • método GET caminho /companies devem obter a lista de todas as empresas
  • método GET path /companies/34 deve obter o detalhe da empresa 34
  • método DELETE caminho /companies/34 deve excluir empresa 34

Em alguns outros casos de uso, se possuímos recursos sob um recurso, por exemplo, Empregados de uma Empresa, alguns dos pontos de extremidade da API da amostra seriam:

  • GET /companies/3/employees deve obter a lista de todos os funcionários da empresa 3
  • GET /companies/3/employees/45 deve obter os detalhes do empregado 45, que pertence à empresa 3
  • DELETE /companies/3/employees/45 deve excluir o empregado 45, que pertence à empresa 3
  • POST /companies devem criar uma nova empresa e devolver os detalhes da nova empresa criada

As APIs não são agora mais precisas e consistentes? ?

Conclusão: os caminhos devem conter a forma plural de recursos e o método HTTP deve definir o tipo de ação a ser executada no recurso.

3) métodos HTTP (verbos)

HTTP definiu alguns conjuntos de métodos que indicam o tipo de ação a ser executada nos recursos.

O URL é uma frase, onde os recursos são substantivos e os métodos HTTP são verbos.

Os métodos HTTP importantes são os seguintes:

  1. GET método GET solicita dados do recurso e não deve produzir nenhum efeito colateral.
    Por exemplo, /companies/3/employees lista de devolução de todos os funcionários da empresa 3.
  2. POST método POST solicita ao servidor que crie um recurso no banco de dados, principalmente quando um formulário da Web é enviado.
    Eg /companies/3/employees cria um novo Empregado da empresa 3.
    POST não é idempotente, o que significa que múltiplos pedidos terão efeitos diferentes.
  3. PUT método PUT solicita ao servidor que atualize o recurso ou crie o recurso, se não existir.
    Eg /companies/3/employees/john solicitará ao servidor que atualize, ou crie se não existe, o recurso John em empregados coleção sob a empresa 3.
    PUT é idempotente, o que significa que múltiplas solicitações terão os mesmos efeitos.
  4. DELETE método DELETE solicita que os recursos, ou sua instância, sejam removidos do banco de dados.
    Eg /companies/3/employees/john/ solicitará ao servidor para excluir o recurso john da coleção de funcionários sob a empresa 3.

Existem alguns outros métodos que discutiremos em outra publicação.

4) códigos de status de resposta HTTP

Quando o cliente levanta uma solicitação para o servidor através de uma API, o cliente deve saber o feedback, se ele falhou, passou ou a solicitação estava errada. Os códigos de status HTTP são um monte de códigos padronizados que tem várias explicações em vários cenários. O servidor sempre deve retornar o código de status correto.
A seguir estão a categorização importante dos códigos HTTP:

2xx (categoria de sucesso)

Esses códigos de status representam que a ação solicitada foi recebida e processada com êxito pelo servidor.

  • 200 Ok A resposta HTTP padrão que representa sucesso para GET, PUT ou POST.
  • 201 Criado Este código de status deve ser retornado sempre que a nova instância for criada. Por exemplo, ao criar uma nova instância, usando o método POST, sempre deve retornar o código de status 201.
  • 204 Nenhum Conteúdo representa a solicitação é processada com sucesso, mas não retornou nenhum conteúdo.
    DELETE pode ser um bom exemplo disso.
    O API DELETE /companies/43/employees/2 irá excluir o empregado 2 e, em troca, não precisamos de dados no corpo de resposta da API, como pedimos explicitamente ao sistema excluir. Se houver algum erro, como se o employee 2 não existisse no banco de dados, o código de resposta não seria da 2xx Success Category mas em torno da 4xx Client Error category .

3xx (categoria Redirecionamento)

  • 304 Não modificado indica que o cliente já possui a resposta no cache. E, portanto, não há necessidade de transferir os mesmos dados novamente.

4xx (categoria de erro do cliente)

Esses códigos de status representam que o cliente levantou um pedido defeituoso.

  • 400 Pedido incorreto indica que a solicitação pelo cliente não foi processada, pois o servidor não conseguiu entender o que o cliente solicita.
  • 401 Não autorizado indica que o cliente não tem permissão para acessar recursos e deve solicitar novamente com as credenciais necessárias.
  • 403 Proibido indica que a solicitação é válida eo cliente é autenticado, mas o cliente não tem permissão para acessar a página ou recurso por qualquer motivo. Por vezes, às vezes, o cliente autorizado não tem permissão para acessar o diretório no servidor.
  • 404 Not Found indica que o recurso solicitado não está disponível agora.
  • 410 Gone indica que o recurso solicitado não está mais disponível, que foi intencionalmente movido.

5xx (Categoria de erro do servidor)

  • 500 Internal Server Error indica que a solicitação é válida, mas o servidor está totalmente confuso e o servidor é solicitado a atender alguma condição inesperada.
  • O serviço 503 Indisponível indica que o servidor está desativado ou não está disponível para receber e processar o pedido. Principalmente se o servidor estiver em manutenção.

5) Convenção de revestimento do nome do campo

Você pode seguir qualquer convenção de caixa, mas certifique-se de que é consistente em toda a aplicação. Se o corpo da solicitação ou o tipo de resposta for JSON , siga seguir camelCase para manter a consistência.

6) Pesquisa, triagem, filtragem e paginação

Todas essas ações são simplesmente a consulta em um conjunto de dados. Não haverá um novo conjunto de APIs para lidar com essas ações. Precisamos anexar os parâmetros de consulta com a API do método GET.
Vamos entender com poucos exemplos como implementar essas ações.

  • Classificação No caso, o cliente deseja obter a lista ordenada de empresas, o ponto final do GET /companies deve aceitar vários params de classificação na consulta.
    Por exemplo, GET /companies?sort=rank_asc classificaria as empresas por sua classificação em ordem crescente.
  • Filtragem Para filtrar o conjunto de dados, podemos passar várias opções através de params de consulta.
    Por exemplo, GET /companies?category=banking&location=india filtra os dados da lista de empresas com a categoria de empresas da empresa e onde a localização é a Índia.
  • Pesquisando Ao pesquisar o nome da empresa na lista de empresas, o ponto final da API deve ser GET /companies?search=Digital Mckinsey
  • Paginação Quando o conjunto de dados é muito grande, dividimos o conjunto de dados em pedaços menores, o que ajuda a melhorar o desempenho e é mais fácil de lidar com a resposta. Por exemplo. GET /companies?page=23 significa obter a lista de empresas na 23ª página.

Se adicionar muitos params de consulta em métodos GET torna o URI muito longo, o servidor pode responder com 414 URI Too long status HTTP, nesses casos, os params também podem ser passados ​​no corpo de solicitação do método POST .

7) Versão

Quando suas APIs estão sendo consumidas pelo mundo, atualizar as APIs com alguma mudança de ruptura também levaria a quebrar os produtos ou serviços existentes usando suas APIs.

http://api.yourservice.com/v1/companies/34/employees é um bom exemplo, que tem o número de versão da API no caminho. Se houver qualquer atualização importante, podemos nomear o novo conjunto de APIs como v2 ou v1.xx