O que é API REST?

Definido em 2000 pelo cientista da computação Dr. Roy Fielding em sua tese de doutorado, o REST oferece aos desenvolvedores um alto grau de flexibilidade, consistência, escalabilidade e eficiência.

As APIs REST oferecem uma forma leve de criar APIs web e são amplamente usadas para facilitar a troca de dados entre aplicações, serviços web e bancos de dados, além de conectar componentes em arquiteturas de microsserviços.

No nível mais básico, uma API é um mecanismo que permite que uma aplicação ou serviço acesse um recurso presente em outra aplicação, serviço ou banco de dados.

A aplicação ou serviço que acessa os recursos é o cliente, enquanto aquele que contém o recurso é o servidor. Algumas APIs, como SOAP ou XML-RPC, impõem um framework rígido para os desenvolvedores. Mas os desenvolvedores podem criar APIs REST com praticamente qualquer linguagem de programação e utilizar diversos formatos de dados.

A única exigência é que sigam os seis princípios de design REST descritos a seguir, também chamados de restrições arquitetônicas.

Todas as solicitações de API pelo mesmo recurso devem ter a mesma aparência, independentemente da origem. A API REST deve garantir que o mesmo dado, como o nome ou endereço de e-mail de um usuário, pertença a somente um identificador de recurso uniforme (URI). Os recursos não devem ser muito grandes, mas devem conter todas as informações que o cliente possa precisar.

No design da API REST, as aplicações do cliente e do servidor devem ser completamente independentes uma da outra. A única informação que a aplicação do cliente deve conhecer é o URI do recurso solicitado; ela não pode interagir com a aplicação do servidor de nenhuma outra forma. Da mesma forma, uma aplicação do servidor não deve modificar a aplicação do cliente além de passar os dados solicitados via HTTP.

As APIs REST são sem estado, ou seja, cada solicitação precisa incluir todas as informações necessárias para seu processamento. Em outras palavras, as APIs REST não requerem quaisquer sessões do lado do servidor. Aplicações do servidor não estão autorizadas a armazenar quaisquer dados relacionados a uma solicitação do cliente.

Quando possível, os recursos devem ser armazenados em cache no lado do cliente ou do servidor. As respostas do servidor também precisam conter informações sobre se o cache é permitido para o recurso entregue. O objetivo é melhorar o desempenho no lado do cliente e, ao mesmo tempo, aumentar a escalabilidade no lado do servidor.

Nas APIs REST, as chamadas e respostas passam por diferentes camadas. Como regra geral, não assuma que as aplicações do cliente e do servidor se conectam diretamente uma à outra. Pode haver vários intermediários diferentes no loop de comunicação. As APIs REST precisam ser projetadas de modo que nem o cliente nem o servidor possam dizer se estão se comunicando com a aplicação final ou um intermediário.

As APIs REST geralmente enviam recursos estáticos, mas, em certos casos, as respostas também podem conter código executável (como miniaplicativos Java). Nesses casos, o código só deve ser executado sob demanda.

As APIs REST se comunicam por meio de solicitações HTTP para executar funções padrão de banco de dados, como criar, ler, atualizar e excluir registros (também conhecidos como CRUD) em um recurso.

Por exemplo, uma API REST usaria uma solicitação GET para recuperar um registro. Uma solicitação POST cria um novo registro. Uma solicitação PUT atualiza um registro, e uma solicitação DELETE exclui um. Todos os métodos HTTP podem ser usados em chamadas de API. Uma API REST bem projetada é semelhante a um site em execução em um navegador web com funcionalidade HTTP integrada.

O estado de um recurso em um determinado instante, ou registro de data e hora, é conhecido como a representação do recurso. Essas informações podem ser enviadas ao cliente em praticamente qualquer formato, como JSON (JavaScript Object Notation), HTML, XLT, Python, PHP ou texto simples. O JSON é amplamente utilizado por ser legível tanto por humanos quanto por máquinas, além de não depender de uma linguagem de programação específica.

Cabeçalhos e parâmetros de solicitação também são importantes em chamadas de API REST, pois incluem informações identificadoras importantes, como metadados, autorizações, identificadores uniformes de recursos (URIs), cache, cookies e mais. Cabeçalhos de solicitação e resposta, juntamente com os códigos de status HTTP convencionais, são usados em APIs REST bem projetadas.

API GraphQL versus REST: qual é a diferença?

Embora a flexibilidade seja uma grande vantagem do design de API REST, essa mesma flexibilidade facilita projetar uma API que seja problemática ou tenha desempenho ruim. Por esse motivo, os desenvolvedores profissionais compartilham as melhores práticas nas especificações da API REST.

A OpenAPI Specification (OAS) define uma interface para descrever uma API de forma que qualquer desenvolvedor ou aplicação consiga descobri-la e compreender totalmente seus parâmetros e recursos. Essas informações incluem os endpoints disponíveis, as operações permitidas em cada um, os parâmetros das operações, os métodos de autenticação e outros detalhes. A versão mais recente, OAS3, inclui ferramentas práticas, como o OpenAPI Generator, para gerar clientes de API e stubs de servidor em diferentes linguagens de programação.

Proteger uma API REST começa com a adoção das melhores práticas do setor. Utilize algoritmos de hash para proteger senhas e HTTPS para garantir a transmissão segura dos dados. Um framework de autorização como o OAuth 2.0pode ajudar a limitar os privilégios de aplicações de terceiros.

Utilizando um registro de data e hora no cabeçalho HTTP, uma API também pode rejeitar todas as solicitações que chegarem após um determinado período. A validação de parâmetros e JSON Web Tokens são outras maneiras de garantir que apenas clientes autorizados possam acessar a API.