O que é uma API REST?

As API têm emergido como a forma mais comum de os programas e os dispositivos interagirem entre si na computação moderna. Uma API é um conjunto de regras que descreve como um programa pode conectar-se com outro e depois comunicar com ele. Como o nome sugere, uma API REST transfere, a cada pedido, o estado de qualquer transação, o que traz vantagens em termos de design, desempenho e recursos em relação a outras abordagens. O REST desenvolveu-se há mais de duas décadas e é uma abordagem muito comum para arquiteturas distribuídas e baseadas em serviços.

O recurso é um conceito fundamental das API REST. Um recurso é um objeto com um tipo, dados associados, relações com outros recursos e um conjunto de métodos operacionais. É muito semelhante à ideia de objetos na programação, embora se definam apenas alguns métodos-padrão, tipificados por HTTP GET, POST, PUT e DELETE. Os recursos podem existir por si próprios ou ser agrupados em coleções que são elas próprias recursos.

Na computação moderna, um modelo comum – igualmente fundamental para as API REST – é o cliente-servidor, no qual um cliente que necessita de um recurso se identifica e comunica com um servidor que pode fornecê-lo. Praticamente todo o tráfego cloud é gerido desta forma, uma vez que oferece a máxima flexibilidade a vários clientes para acederem a múltiplos servidores. Este princípio também se aplica às chamadas arquiteturas «sem servidor», em que um mediador de serviços toma o lugar de um servidor conhecido do cliente.

A arquitetura das API REST começou a evoluir em 1993, quando começaram a surgir sites de uso geral.

A rápida expansão da Web levou a propostas concorrentes para extensões para o HyperText Transfer Protocol (HTTP) original. O World Wide Web Consortium (W3C) e a Internet Engineering Task Force (IETF) iniciaram os trabalhos de avaliação e formalização de novas versões dos standards HTTP, HyperText Transfer Language (HTML) e URI.

Após seis anos a trabalhar na normalização HTTP e URI, o investigador Roy Fielding definiu o REST em 2000, determinando que o estilo arquitetónico verificasse os desenvolvimentos futuros dos protocolos Web e identificasse extensões incompatíveis com os objetivos de comportamento e desempenho da Web.

Subsequentemente, os conceitos REST revelaram-se altamente adaptáveis à evolução da computação conectada. Desde 2015, a OpenAPI Initiative, sob o patrocínio da Linux Foundation (com membros como a Google, a IBM, a Microsoft e o PayPal), criou a OpenAPI Specification, baseada em regras RESTful. Esta última publica ficheiros de interface de leitura automática para descrever, produzir, consumir e visualizar serviços RESTful.

As aplicações implementadas com base nos ficheiros de interface OpenAPI podem gerar automaticamente a documentação de métodos, parâmetros e modelos. Além de fornecer um foco industrial para a padronização de cabeçalhos, códigos, descrições de recursos e inovações futuras, a iniciativa OpenAPI fornece ferramentas, materiais de referência e boas práticas. Estes são especialmente importantes na criação, verificação e utilização adequada da autenticação e da segurança dos dados de uma forma RESTful, em que a OpenAPI Initiative tem uma atenção particular.

1. Interface uniforme

Todos os pedidos efetuados através de uma API REST devem respeitar as regras de formatação dessa API. Independentemente do cliente que faz o pedido, deve colocar cada elemento de informação onde qualquer outro cliente o faria. Um exemplo é o URL (ou Uniform Resource Locator) utilizado para identificar recursos via HTTP, que é um exemplo de um URI (Uniform Resource Identifier) que pode ter alcances maiores.

2. Separação cliente-servidor

As API REST requerem que as aplicações cliente e servidor sejam totalmente independentes umas das outras. O cliente só precisa de saber o nome completo do recurso que deseja no espaço virtual permitido pela API. Caso contrário, o único conhecimento que o cliente e o servidor têm um do outro é o que é trocado por transações da API.

3. Ausência de estado

Cada pedido de cliente deve conter todas as informações necessárias ao seu tratamento, e o servidor não precisa de conservar quaisquer informações sobre esse pedido depois de o receber. Não há conceito de sessão no design API REST, e o servidor não tem estado em relação a qualquer cliente em particular.

4. Capacidade de cache

Em contraste com a ausência de estado por cliente do servidor, os recursos devem poder ser armazenados em um ou mais pontos dentro ou entre cliente e servidor. No caso do servidor, se um recurso específico tiver sido servido e for provável que seja novamente solicitado dentro de determinado período, deverá ser colocado em cache para uma resposta ulterior mais rápida. O cliente deve tomar uma decisão semelhante relativamente aos recursos recebidos. O servidor deve indicar através da API se um recurso pode ser colocado em cache de forma local e segura no cliente, incluindo a duração de vida dos dados, quando apropriado. O design da cache, embora não faça parte de uma especificação API RESTful, é essencial para o desempenho, e os designers da API devem estar cientes de como isto pode ser aplicado na prática.

5. Arquitetura de sistema por camadas

Uma consequência da separação cliente-servidor, da ausência de estado e da capacidade de cache é que um cliente não pode supor se está a comunicar diretamente com um servidor que possui um recurso específico, ou se está a ser servido por um intermediário como um mediador de serviços, um repartidor de carga, um sistema de distribuição de conteúdo ou outro subsistema mais próximo do cliente do que o servidor. Isto proporciona aos criadores de sistemas e infraestruturas uma flexibilidade considerável para maximizar a eficiência e a fiabilidade da satisfação dos pedidos na infraestrutura global, com e sem fios. Está subjacente à funcionalidade de edge computing.

6. Código a pedido

Embora as API REST possam e frequentemente sirvam apenas dados para consumo pelo cliente, é cada vez mais comum que o código seja entregue para execução no cliente, como objetos Java ou aplicações web Javascript. Se for implementado, este código só pode ser executado a pedido do cliente.

As API REST podem tratar praticamente qualquer pedido de acesso, formato de dados, controlo de recursos ou mensagem de estado, mas a regra de ausência de estado significa que cada pedido deve conter qualquer autenticação necessária para verificar o pedido, a definição precisa do recurso necessário e a ação exata requerida.

Por exemplo, uma API de sistema de ficheiros que não seja RESTful pode responder a um pedido de leitura de um ficheiro devolvendo um identificador de ficheiro, um pequeno token atribuído a uma sessão de modo que o cliente seja capaz de efetuar leituras repetidas apenas por referência a esse identificador. Já uma API REST teria de enviar uma autorização do cliente em cada ocasião, mas também o identificador exato completo do recurso, juntamente com a localização precisa no ficheiro dos dados a ler. O controlo cabe ao cliente.

As API REST passam todas estas informações através de uma combinação de cabeçalhos e campos de parâmetros, e podem trocar os dados em qualquer formato. Um padrão muito comum é o JSON, o formato de Notação de Objetos Javascript, o qual, apesar do nome, é legível tanto por humanos quanto por máquinas, a olho nu ou usando qualquer uma das linguagens de programação mais populares.

A eficiência da API REST deve ser tida em conta, especialmente nos casos em que se devem tratar transferências de grandes dados ou fluxos críticos em termos de tempo, ou, inversamente, quando pequenas quantidades de dados provêm de fontes com restrições de recursos como os sistemas IoT.

A API OVHcloud é um serviço web que permite aos nossos clientes comprar, gerir, atualizar e configurar produtos da OVHcloud sem utilizar a interface gráfica de cliente. Baseia-se na API RESTful mais recente, a fim de gerir quase tudo no universo OVHcloud. A API foi concebida para ser simples e fácil de utilizar, e os fragmentos de código são fornecidos numa grande variedade de idiomas.

O OVHcloud Manager (V6) já está acessível através da API OVHcloud, e cada novo produto e versão de produto incluirão a compatibilidade com a API. A consola API Explorer pode navegar na API e descobrir todas as funções disponíveis para os produtos da OVHcloud, mesmo para quem não está registado como programador. Também pode selecionar um produto e navegar na API dedicada para descobrir ações relacionadas.

A utilização da API RESTful da OVHcloud permite um desenvolvimento rápido e simples de scripts para funções personalizadas, automatização, várias tarefas simultâneas e criação de ferramentas de implementação e gestão IaaS/PaaS. Está disponível apoio de linguagem explícita para C, C++, C#, Java, Perl, PHP, Python, Ruby e muitas mais.