API Rest: Introdução às Interfaces de Programação

O que é uma API Rest?

Você já se perguntou o que é uma API Rest? A API Rest (Representational State Transfer) é um conjunto de regras que permite a comunicação entre sistemas, utilizando os princípios da arquitetura REST. 

Assim, essas APIs são baseadas em recursos, cada um identificado por uma URL única, e usam métodos HTTP padrão como GET, POST, PUT e DELETE para realizar operações. 

Em suma, elas são projetadas para serem escaláveis, flexíveis e independentes de plataforma, facilitando a integração entre diferentes serviços e aplicações.

Histórico e evolução das APIs Rest

O conceito de REST foi introduzido por Roy Fielding em sua tese de doutorado em 2000. Desde então, REST se tornou a abordagem padrão para a criação de APIs devido à sua simplicidade e eficiência. 

Com a crescente demanda por aplicações web e móveis, as APIs RESTful evoluíram para suportar uma ampla variedade de casos de uso, desde simples integrações até complexos sistemas distribuídos. 

Em resumo, empresas de todos os tamanhos começaram a adotar REST para construir suas interfaces de programação de aplicativos, apreciando sua capacidade de facilitar a comunicação entre sistemas diferentes. 

Além disso, a popularidade das APIs RESTful cresceu ainda mais com a ascensão de tecnologias como o microserviços, que dependem de uma comunicação eficiente e padronizada entre serviços. 

Hoje, consideramos o REST um dos pilares fundamentais no desenvolvimento de software moderno, pois suporta a conectividade de uma vasta gama de dispositivos e aplicações.

Princípios fundamentais da API Rest

Para que os desenvolvedores de software mantenham um padrão na criação de interfaces de programação, existem arquiteturas de software que estabelecem regras e boas práticas para o desenvolvimento de uma API.

Uma dessas arquiteturas é a REST - Transferência Representacional de Estado (Representational State Transfer, em inglês). As APIs que seguem rigorosamente as regras desse padrão são conhecidas como RESTful APIs.

Uma REST API deve incorporar alguns princípios fundamentais, tais como:

Interação Cliente-Servidor em API Rest (Client-Server)

Um dos princípios fundamentais no desenvolvimento de APIs, incluindo as que seguem a arquitetura REST, é a interação entre clientes e servidores.

No contexto das APIs Rest, o cliente é uma aplicação ou usuário que solicita informações. Por outro lado, o servidor é a aplicação que fornece a informação solicitada. Simplificando, o cliente faz uma requisição e o servidor fornece uma resposta.

A API Rest atua como a porta de entrada para o servidor. Quando um cliente faz uma requisição, a API Rest a recebe, comunica-se com o servidor e retorna a resposta ao cliente. Esse processo é essencial para garantir uma comunicação eficaz e eficiente entre as partes.

Uma analogia popular para entender esse princípio é a de um restaurante:

• O freguês representa o cliente.
• O garçom atua como a API Rest.
• O cozinheiro é o servidor.

Essa analogia ilustra como as responsabilidades podem ser divididas entre os sistemas, permitindo uma maior independência e simplificando a troca de dados na internet.

Ao adotar o princípio de interação cliente-servidor em APIs Rest, é possível melhorar a eficiência e a clareza na comunicação entre clientes e servidores.

Sem Estado em API Rest (Stateless)

O princípio "sem estado" é um conceito essencial em APIs Rest. Esse princípio estabelece que cada solicitação feita pelos clientes aos servidores deve ser independente e autocontida. Em outras palavras, cada "pedido" precisa conter todos os dados necessários para que o servidor possa processar a requisição sem depender de informações de requisições anteriores.

Esse comportamento, conhecido como stateless ou sem estado, implica que o servidor não precisa armazenar informações sobre solicitações anteriores. Cada requisição é tratada de forma isolada, o que simplifica o gerenciamento do estado no servidor e melhora a escalabilidade da API Rest.

Adotar o princípio stateless nas APIs Rest proporciona maior eficiência e flexibilidade, pois reduz a necessidade de armazenamento de dados de sessões passadas e facilita a manutenção e a escalabilidade dos serviços oferecidos.

Armazenamento em Cache em API Rest (Cacheable)

Imagine que você é um usuário de um site que oferece previsões do tempo. Essas previsões, armazenadas no banco de dados do servidor do site de clima, não mudam significativamente a cada segundo ou poucos minutos.

Faz sentido que o servidor do site execute uma consulta no banco de dados toda vez que o cliente solicitar a previsão do tempo? Em muitos casos, não é necessário.

Para otimizar o desempenho das APIs Rest, é fundamental implementar um sistema de armazenamento em cache (geralmente um banco de dados em memória). Isso garante que, quando vários usuários solicitam repetidamente a mesma informação em um curto espaço de tempo, os servidores não precisem processar a mesma requisição constantemente, resultando sempre nas mesmas respostas.

Essa abordagem oferece duas vantagens principais: redução das interações entre servidores e bancos de dados, o que diminui os custos operacionais, e melhoria na performance das APIs Rest, proporcionando respostas mais rápidas às solicitações dos clientes. Como consequência, a experiência do usuário é significativamente aprimorada devido ao melhor desempenho das aplicações.

Interface Uniforme em API Rest (Uniform Interface)

O princípio da interface uniforme é fundamental para uma API Rest, determinando que ela deve seguir um conjunto consistente de regras para suas operações. Isso inclui o uso adequado de métodos e status HTTP para estabelecer uma comunicação sólida entre o cliente e o servidor.

Além disso, é comum que APIs Rest e servidores utilizem estruturas de dados como JSON ou XML para a troca de informações, com o JSON sendo uma das mais populares. Conhecido como "Notação de Objeto JavaScript" (JavaScript Object Notation, em inglês), o JSON permite o envio de dados de forma estruturada e compreensível. Veja o exemplo abaixo:

{
"nome": "Fulano",
"sobrenome": "de Tal",
"idade": 20,
"endereco": {
"cidade": "São Paulo",
"uf": "SP"
}
}

Adotar uma interface uniforme nas APIs Rest assegura uma integração eficiente e clara, melhorando a comunicação entre o cliente e o servidor.

Sistema em Camadas em API Rest (Layered System)

Uma API Rest funciona como a porta de entrada para um servidor, mas o servidor não é necessariamente composto por uma única aplicação. Em vez disso, os servidores podem ser estruturados em camadas, cada uma com responsabilidades específicas, como autenticação de usuário, manipulação de banco de dados ou comunicação com serviços externos de terceiros.

Essa arquitetura em camadas permite que o cliente não precise entender a complexidade interna do servidor. Utilizando a interface da API Rest, a comunicação com o servidor torna-se simplificada, facilitando o processo de integração.

Ao adotar um sistema em camadas, as APIs Rest garantem uma comunicação eficiente e organizada entre o cliente e o servidor, promovendo uma integração mais fluida e eficaz.

Código sob Demanda em API Rest (Code On Demand)

O código sob demanda é um princípio opcional em uma API Rest. Esse conceito define que uma interface de programação deve ser capaz de responder às solicitações dos clientes com códigos executáveis, que os próprios clientes são responsáveis por executar, se necessário.

Embora o uso do código sob demanda seja menos comum atualmente, ele foi amplamente utilizado no passado, especialmente para fornecer recursos adicionais em navegadores de internet mais antigos.

A principal razão para a diminuição do uso desse princípio é a segurança. Scripts executáveis podem introduzir vulnerabilidades que comprometem a segurança dos usuários, tornando essa abordagem menos favorável nas práticas modernas de desenvolvimento de APIs.

Como funciona uma API Rest?

As APIs Rest (Representational State Transfer) são amplamente utilizadas devido à sua simplicidade e eficiência na comunicação entre sistemas. 

Elas operam sobre o protocolo HTTP, utilizando métodos padrão para realizar operações em recursos.

A seguir, exploramos os principais componentes e conceitos que compõem uma API Rest.

Métodos HTTP comuns (GET, POST, PUT, DELETE)

Os métodos HTTP são a base da interação com APIs Rest, permitindo diferentes operações em recursos. Esses métodos incluem:

• GET: Utilizado para recuperar informações de um recurso. Por exemplo, uma requisição GET para /users pode retornar uma lista de usuários.
• POST: Em resumo, é utilizado para criar um novo recurso. Por exemplo, uma requisição POST para /users com os dados de um novo usuário resultará na criação desse usuário no servidor.
• PUT: Utilizado para atualizar um recurso existente. Por exemplo, uma requisição PUT para /users/1 com dados atualizados modificará as informações do usuário com ID 1.
• DELETE: Por fim, é utilizado para remover um recurso. Por exemplo, uma requisição DELETE para /users/1 resultará na exclusão do usuário com ID 1.

Estrutura de URLs e recursos

A estrutura de URLs em APIs Rest reflete a hierarquia dos recursos de forma intuitiva. Em resumo, cada recurso recebe uma URL única como identificação.

Por exemplo, em uma aplicação de gerenciamento de usuários, /users pode representar todos os usuários, enquanto /users/1 representa um usuário específico com ID 1. 

Em resumo, essa abordagem facilita a navegação e a compreensão dos recursos disponíveis na API.

Headers e Status Codes

Os cabeçalhos HTTP (headers) desempenham um papel essencial na comunicação entre o cliente e o servidor, fornecendo informações adicionais sobre a requisição ou a resposta. 

Alguns cabeçalhos comuns incluem:

• Content-Type: Indica o tipo de conteúdo enviado ou recebido (por exemplo, application/json).
• Authorization: Utilizado para enviar credenciais de autenticação.
• Accept: Especifica os tipos de conteúdo que o cliente aceita como resposta.

Além disso, os códigos de status HTTP indicam o resultado da requisição, ajudando a identificar o sucesso ou falha das operações realizadas. 

Alguns códigos de status comuns incluem:

• 200 OK: A requisição foi bem-sucedida.
• 201 Created: Um novo recurso foi criado com sucesso.
• 400 Bad Request: A requisição é inválida ou malformada.
• 404 Not Found: O recurso solicitado não foi encontrado.

Compreender como funciona uma API Rest é essencial para qualquer desenvolvedor que trabalha com integrações entre sistemas. 

Assim, ao utilizar métodos HTTP, estruturas de URLs bem definidas, cabeçalhos e códigos de status, as APIs RESTful proporcionam uma maneira eficiente e padronizada de comunicação, permitindo a criação de aplicações web escaláveis e robustas. 

Tipos de Parâmetros em API Rest

Existem várias formas de enviar e receber dados durante requisições e respostas em uma API Rest. Esses parâmetros podem ser classificados em diferentes tipos:

Route Params

Também conhecidos como parâmetros de rota, os route params fazem parte da URL à qual o cliente faz a requisição. Por exemplo, considere a URL https://dominio.com/livro/9786555521368. Neste caso, o cliente envia um dado ao servidor, como o código ISBN do livro, diretamente na rota.

Query Params

Os query params ou parâmetros de consulta são incluídos na URL da requisição, mas de forma diferente dos route params. Por exemplo, ao pesquisar por um animal no Google, a URL gerada é algo como https://www.google.com/search?q=gato. Aqui, q=gato é o parâmetro de consulta que informa o que o cliente deseja buscar. Os query params são separados da rota por um ponto de interrogação ?, e múltiplos parâmetros podem ser adicionados usando o caractere &, como em http://dominio.com/rota?param1=valor1&param2=valor2.

Body Params

Os body params ou parâmetros do corpo da requisição permitem o envio de estruturas de dados como JSON ou XML entre o cliente e o servidor. Por exemplo, ao enviar informações sobre um livro, o cliente pode enviar os dados organizados no corpo da requisição da seguinte forma:

POST https://dominio.com/livro
{
"livro": "Pequeno Príncipe",
"codigo": "9786555521368"
}

Para testar a API que você desenvolve, ferramentas específicas podem ajudar no envio de body params.

Headers

Os cabeçalhos HTTP, ou headers, são informações adicionais que clientes e servidores trocam para uma comunicação mais precisa. Eles fornecem detalhes essenciais sobre os dados enviados ou recebidos em uma requisição. Exemplos de headers incluem:

• Content-Type: Indica o tipo de conteúdo transportado, como text/html ou application/json.
• Content-Length: Representa o tamanho do conteúdo no corpo da requisição.

Você pode consultar a documentação oficial da Mozilla para desenvolvedores para mais detalhes sobre outros cabeçalhos HTTP.

Vantagens de utilizar APIs Rest