O que é um endpoint de API?

Uma API é um ponto intermediário que possibilita que aplicações de software se comuniquem entre si para trocar dados, recursos e funcionalidades. É um conjunto de protocolos e regras que definem como um cliente da API (o software que faz uma solicitação) pode se comunicar com um servidor para acessar dados e funções. Utilizando uma API, os desenvolvedores podem aproveitar dados e serviços já existentes e os proprietários de aplicações podem compartilhar ou comercializar os mesmos dados e serviços.

Os endpoints funcionam um pouco como os números de telefone: assim como um usuário disca um número de telefone para entrar em contato com uma determinada pessoa ou empresa, os clientes de API (o software que faz uma chamada de API) fornecem um URL de endpoint para acessar um recurso específico. Um URL de endpoint fornece o local de um recurso em um servidor de API e ajuda a conectar o cliente de API ao recurso que está sendo solicitado. Basicamente, ele diz ao servidor: "o recurso de que preciso está localizado aqui".

Os endpoints de APIs podem possibilitar que um cliente de API solicite todos os tipos de dados de uma API, com casos de uso que vão desde atualizações em tempo real de aplicações de software de redes sociais até funcionalidades como incorporação de áudio ou vídeo, carregamento de notícias ou criação de uma nova postagem.

Endpoints de APIs seguros e formatados de forma adequada são uma parte essencial do funcionamento das APIs. As APIs simplificam o design e o desenvolvimento de novas aplicações e serviços (porque permitem que os desenvolvedores criem recursos e serviços existentes) e a integração e o gerenciamento dos já existentes. Elas também oferecem benefícios significativos para desenvolvedores e organizações em geral, incluindo colaboração aprimorada, inovação acelerada, maior agilidade, escalabilidade, segurança e muito mais. Os endpoints de APIs permitem a troca de recursos que torna essa integração possível.

Para que as APIs funcionem corretamente, os pontos de extremidade da API devem ser precisos, intuitivos, detectáveis e autenticados, caso contrário a comunicação entre o cliente e o servidor poderá falhar, levando à perda de funcionalidade e da satisfação do usuário. Simplificando, os endpoints de APIs possibilitam que os clientes de APIs localizem e acessem com sucesso os recursos e as funções solicitados.

Os endpoints de APIs geralmente são encontrados na documentação de uma API, que é onde os desenvolvedores colocam informações da API, como que tipo de solicitações uma API aceitará e como as solicitações devem ser formatadas. O ideal é que essa documentação também inclua uma lista de todos os endpoints de APIs disponíveis e uma breve descrição de suas funcionalidades.

No contexto de API REST (um estilo arquitetônico de software frequentemente usado para aplicações da web), o processo tem a seguinte aparência:

O processo começa quando um cliente de API envia uma solicitação de recurso (chamada de API) para o endpoint da API correspondente. Os endpoints são acessados usando métodos de solicitação HTTP, como POST, GET, PUT, PATCH e DELETE. Esses métodos indicam a ação que o cliente deseja realizar no recurso especificado.

Por exemplo, se um cliente deseja recuperar uma lista de totais de medalhas olímpicas para um determinado ano do banco de dados hipotético Olympicfacts.com, uma solicitação GET é enviada para o seguinte URL de endpoint: 

https://api.olympicfacts.com/v1/{year}

Essa solicitação retornaria uma lista do total de medalhas olímpicas por país. (v1 em nosso endpoint hipotético indica a versão da API, uma prática comum no controle de versões de APIs.) Se o cliente quisesse um total para um país específico em um determinado ano, um identificador seria adicionado ao URL base: 

https://api.olympicfacts.com/v1/year/{id}

Neste exemplo, o identificador {id} é usado para indicar de qual país o cliente deseja receber informações.

Além disso, uma solicitação pode incluir:

• Cabeçalhos: os cabeçalhos podem fornecer informações adicionais sobre a solicitação, como um cabeçalho Aceitar, que especifica os tipos de mídias aceitos
  
  
• Parâmetros: os parâmetros de consulta podem ser adicionados ao URL de base ou ao corpo da solicitação para filtrar ainda mais os critérios de pesquisa ou adicionar outras especificações.
  
  
• Corpo da solicitação: um corpo da solicitação inclui os dados necessários para criar ou modificar um recurso. Por exemplo, se a solicitação for para criar um novo blog (solicitação POST), o conteúdo do novo blog será incluído no corpo da solicitação.
  

Depois que o servidor autentica a solicitação e valida a entrada, ele recupera os dados solicitados e retorna a resposta ao cliente. Muitas organizações usam API Gateways para executar essas funções e gerenciar o fluxo de tráfego de APIs.

Uma API REST (também chamada de API RESTful ou web API RESTful) é uma API que segue os princípios de design do estilo arquitetônico de transferência de estado representacional (REST).¹ GraphQL é uma linguagem de consulta de código aberto e tempo de execução do servidor que especifica como os clientes devem interagir com APIs.²

GraphQL e REST são tecnologias baseadas em recursos que aceitam formatos de dados similares (JSON e XML, por exemplo) e permitem que os clientes solicitem dados de servidores usando métodos HTTP. No entanto, eles diferem em seus requisitos de solicitação e recuperação de dados, entre outras diferenças. Vamos nos concentrar em uma diferença importante relacionada a endpoints.

As APIs REST usam vários endpoints e têm endpoints diferentes para cada recurso. Quando o cliente solicita um recurso, o servidor retorna todos os dados associados ao recurso, mesmo que o cliente necessite apenas de um subconjunto dos dados. Isso é conhecido como overfetching. Se um cliente precisar de dados espalhados por vários recursos, será necessário fazer chamadas de API separadas para cada um desses recursos para compilar os dados necessários.

O GraphQL expõe modelos de dados usando um único endpoint e usa uma sintaxe que permite aos clientes fazer solicitações de API em uma única linha, ou algumas linhas, para especificar exatamente aquilo de que precisam. As consultas do GraphQL podem seguir referências entre recursos e realizar tarefas complexas de recuperação de dados em uma única solicitação. Isso ajuda a eliminar problemas de under e overfetching e a necessidade de fazer múltiplas chamadas de API.

Nem as APIs REST nem as GraphQL são inerentemente superiores; são ferramentas diferentes, adequadas a tarefas diferentes.³

Fundamental para qualquer bom design de API é a fase de testes. As aplicações modernas geralmente usam APIs para integrar funções de outros softwares ou são criadas usando arquiteturas de microsserviços (que dependem de APIs para comunicação entre serviços díspares). Testar os endpoints de APIs é essencial para garantir confiabilidade.

Existem opções de testes manuais para APIs e opções de testes que utilizam automação, bem como inúmeras ferramentas e plataformas de testes (tanto de código aberto quanto proprietárias) que as empresas podem utilizar.

Os testes manuais de endpoints de APIs podem ser mais lentos e menos eficientes, mas também mais precisos e personalizados para casos de uso específicos. Testes funcionais seria simplesmente enviar uma solicitação de uma aplicação para garantir que a resposta correta seja dada. Em um exemplo de redes sociais, isso pode significar o envio de uma solicitação para uma nova postagem de um determinado usuário e a verificação para garantir que a postagem retornada seja realmente a correta.

Outros tipos de testes manuais envolvem: 

• enviar muitas solicitações de uma só vez para ver como o servidor lida com a carga de solicitações
  
  
• verificar se a API se integra corretamente a outros serviços
  
  
• determinar a velocidade e o tempo de resposta de uma determinada solicitação
  
  
• fornecer intencionalmente uma solicitação inválida para verificar se a mensagem de erro correta é retornada

Testes automatizados feitos por meio de uma plataforma de gerenciamento de API podem oferecer diversas vantagens:

• reduz a possibilidade de erro humano
  
  
• é mais eficiente na verificação da validade de vários endpoints de APIs
  
  
• pode melhorar a velocidade dos testes podendo reduzir custos a longo prazo, após os sistemas de testes automatizados serem estabelecidos (economizando tempo dos funcionários, por exemplo)
  
  
• Alinha os testes ao longo de protocolos, padrões e permissões uniformes

Em geral, cada um deve retornar a resposta pretendida, em termos de formato, dados retornados e código de status.

Como os endpoints das APIs oferecem uma forma de aplicações e sistemas internos e externos acessarem e integrarem dados, também apresentam um possível ponto de entrada para agentes mal-intencionados. Ataques de distributed denial-of-service (DDoS) podem utilizar solicitações legítimas em quantidades absurdas para inundar um servidor. Outros tipos de ataques podem tentar usar endpoints de APIs para extrair mais informações do que o cliente está autorizado a receber ou usar endpoints de APIs para instalar malware ou código malicioso.

Há várias maneiras pelas quais uma organização pode manter a segurança de seus endpoints de APIs e a segurança geral de APIs, incluindo:

Métodos de autenticação, como autenticação de chave de API e OAuth, garantem que somente usuários autorizados possam acessar os dados.

O HTTPS (versão mais segura do protocolo de transferência de hipertexto ou HTTP) utiliza segurança da camada de transporte (TLS) para criptografar as comunicações entre o cliente e o servidor. Isso aumenta a segurança das transferências de dados.

Limitação de taxa é um termo geral que se refere aos esforços para definir quantidades máximas de solicitações, o que pode ajudar a evitar ataques DDoS e manter a estabilidade do sistema. Diferentes limites também podem ser aplicados a diferentes endpoints de APIs.

Se os ataques forem gerados a partir de um local específico, a filtragem geográfica poderá ser usada para bloquear ou limitar o acesso a partir desses locais.

Um gateway de API é uma camada de software que atua como intermediário entre dispositivos clientes e servidores. É um ponto central que aceita todas as chamadas de API e as encaminha para os serviços solicitados. Muitos desses recursos de segurança (além dos recursos de Monitoring and Analytics de APIs) podem ser implementados em um API gateway, e o uso de um API gateway promove a aplicação consistente de protocolos de segurança em um ambiente de API.

Os recursos de APIs são conjuntos de dados ou objetos fornecidos pelas APIs. Os recursos variam de acordo com a API em questão, mas os tipos de conteúdo incluem texto, tabelas, arquivos de origem, áudio, vídeo, imagens, usuários, produtos e muito mais.

Um endpoint de API é o local específico desses recursos em um servidor. É um ponto de contato entre um cliente e um servidor de API, para onde as chamadas de API são direcionadas.

Pense em uma listagem de empresas para uma loja. A listagem fornece a localização da loja (endpoint) e como contatá-la para solicitar informações como horário de funcionamento da loja e inventário de produtos (recursos).

Uma chave de API é um método para verificar e autenticar a identidade e a autenticidade de um cliente que faz uma chamada de API. Chaves de APIs são sequências de caracteres gerados aleatoriamente, emitidos por um provedor de API para usuários registrados da API. Quando um dispositivo cliente faz uma chamada de API, ele inclui a chave de API. O API gateway ou servidor de API que recebe a chamada primeiro verifica a chave para validar a identidade do cliente antes de atender à solicitação de API. Se a chave não corresponder a nenhuma das chaves permitidas, o servidor recusará a chamada da API e emitirá uma mensagem de rejeição.

As organizações usam chaves de APIs para autenticar clientes e projetos individuais, rastrear e identificar padrões de tráfego, bloquear uso indesejado e muito mais.

Os endpoints de APIs, conforme discutido, atuam como uma interface entre clientes e servidores para onde os clientes da API direcionam solicitações para determinados dados ou funções de uma API. As chaves de API podem ser usadas para melhorar a segurança de todo o ambiente de APIs de uma empresa e suas integrações de APIs.