O que é uma API REST?

Originalmente definido no ano 2000 pelo cientista da computação Dr. Roy Fielding em sua tese de doutorado, o REST oferece um nível relativamente alto de flexibilidade, escalabilidade e eficiência para desenvolvedores. Por essas razões, as APIs REST se consolidaram como um método comum para conectar componentes e aplicações em uma arquitetura 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 dentro de outra aplicação ou serviço. A aplicação ou o serviço que acessa os recursos é o cliente e a aplicação ou serviço que contém o recurso é o servidor. Algumas APIs, como SOAP ou XML-RPC, impõem uma estrutura rígida aos desenvolvedores. Mas os desenvolvedores podem criar APIs REST utilizando praticamente qualquer linguagem de programação e aceitar uma variedade de formatos de dados. O único requisito é que sigam os seis princípios de design REST a seguir, também conhecidos como restrições de arquitetura.

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 entregues a um cliente em praticamente qualquer formato, incluindo JavaScript Object Notation (JSON), HTML, XLT, Python, PHP ou texto simples. JSON é popular porque pode ser lido por humanos e máquinas – e é independente da linguagem de programação.

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.

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) estabelece uma interface para descrever uma API de forma que qualquer desenvolvedor ou aplicação possa descobri-la e entender completamente seus parâmetros e recursos. Essas informações incluem endpoints disponíveis, operações permitidas em cada endpoint, parâmetros de operação, métodos de autenticação e mais. 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.

A proteção de uma API REST também começa com as melhores práticas do setor. Use algoritmos de hashing para a segurança da senha e HTTPS para a transmissão segura de dados. Um framework de autorização como o OAuth 2.0 pode 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.