7 práticas recomendadas para nomear seus endpoints de API

Um endpoint de API é um ponto de conexão entre dois programas de software. As APIs têm endpoints para cada recurso. Os terminais especificam a localização exata de um recurso no servidor.

Quando um aplicativo cliente solicita informações do servidor, ele passa pela API. Que então acessa a solicitação e processa uma resposta do servidor. A API então transfere as informações solicitadas do terminal para o aplicativo.

Sua API é eficiente se puder se comunicar efetivamente por meio de seus endpoints. Facilita o acesso dos usuários aos recursos, melhorando a experiência do usuário.

Como funciona um endpoint de API?

Os sistemas integrados se comunicam por meio de APIs. Um sistema envia uma solicitação para a API, usando um formato como SOAP ou REST. O servidor recebe as solicitações e transfere a resposta de volta para a API. A localização desse recurso solicitado é o terminal.

Antes de um terminal processar uma solicitação, o cliente deve fornecer uma URL, cabeçalhos e um corpo. Os cabeçalhos contêm metadados sobre uma solicitação e os dados de detalhes do corpo enviados ao servidor. Um servidor também pode se conectar a um banco de dados que os métodos de API podem acessar.

Os endpoints da API geralmente funcionam com métodos HTTP, como GET, DELETE, PATCH ou POST. Os métodos determinam como usar um endpoint. Quando um cliente envia uma solicitação, ele precisa formulá-la para incluir o método de solicitação, bem como a URL, por exemplo:

GET https://example.com/books/authors

Nomear é difícil, seja endpoints de API, dispositivos de hardware em rede ou funções e variáveis. Você deve aprender sobre algumas práticas recomendadas que pode usar para garantir que seus endpoints de API sejam um ativo.

1. Use uma barra

Sempre use barras para separar recursos de URI. As barras também ajudam a mostrar a hierarquia de recursos. O seguinte é um exemplo:

2. Use substantivos, não verbos

Você só deve usar substantivos para nomear um recurso. Os substantivos descrevem para que serve um recurso, em oposição a um verbo que descreve o que um recurso faz. Aqui está um exemplo de uma maneira boa e ruim de nomear os endpoints da API.

Boa nomenclatura:

Nomenclatura incorreta:

http://example.com/api/books

3. Use substantivos plurais, não singulares

Você sempre deve nomear seus endpoints de API em substantivos plurais. Isso indica a um usuário que há mais de um recurso no servidor. Usar um substantivo no singular pode confundir o usuário e fazê-lo pensar que há apenas um recurso.

Boa nomenclatura:

Nomenclatura incorreta:

http://example.com/api/books/3

4. Use letras minúsculas

Você deve digitar todas as URLs em letras minúsculas. Isso inclui URLs de endpoint de API. Aqui está um exemplo:

Boa nomenclatura:

http://example.com/api/Books/3

Nomenclatura incorreta:

http://example.com/api/books/3

5. Use hífens para separar palavras

Use hifens para separar palavras combinadas. Hífens resultam em frases mais legíveis do que maiúsculas e minúsculas ou sublinhados. Eles também são melhores para fins de SEO.

Boa nomenclatura:

Nomenclatura incorreta:

6. Não adicione extensões de arquivo

Você não precisa adicionar uma extensão de arquivo aos endpoints da API. Embora não afete a saída, uma extensão dificulta a leitura do recurso. Também torna o recurso menos flexível, quebrando-o se a extensão mudar no futuro.

Boa nomenclatura:

Nomenclatura incorreta:

7. Incluir controle de versão

Você sempre deve nomear seus endpoints de API de acordo com a versão. Isso é importante se você estiver fazendo grandes alterações na API. Ajuda a diferenciar entre duas ou mais versões de API de onde vem o recurso. Você pode indicar a versão no início do endpoint.

Por exemplo:

Por que considerar as práticas recomendadas de API?

As APIs se tornaram a espinha dorsal da programação moderna. Eles melhoram a colaboração, incentivam a inovação e melhoram a segurança do aplicativo.

Seja usando novas ferramentas ou gerenciando as existentes, as APIs simplificam o processo. Portanto, é essencial ter endpoints que melhorem a experiência do usuário. A nomenclatura e a estrutura de seus endpoints de API determinam o desempenho de sua API.

Certifique-se de usar as práticas recomendadas para criar endpoints de API eficientes.