Descubra o universo das REST APIs: da arquitetura REST aos métodos HTTP, explore o essencial para uma integração eficaz e segura.
Tempo de Leitura: 8 minutos
O que é uma API?
Com o crescimento do número de software no mercado, existe a necessidade de realizar conexões entre eles para conseguirem se comunicar entre si. Para isso, é preciso seguir alguns protocolos e padrões que permitam que essas aplicações possam trocar informações com sucesso.
As Interfaces de Programação de Aplicações, também conhecida como APIs (Application Programming Interface, em inglês) possuem exatamente essa finalidade. Por meio delas, é possível estabelecer uma integração entre diferentes sistemas, que conectados podem promover uma melhor experiência ao usuário, além de agilizar o desenvolvimento de software.
Nesse artigo, você entenderá como uma API funciona, a sua relação com um dos protocolos de comunicação mais utilizados na internet, o HTTPS, além de conhecer as características de uma interface de programação.
Protocolo HTTPS
Nesse exato momento, você está utilizando o protocolo HTTPS, sabia? É muito provável que se você olhar para a URL do site em que você lê esse artigo, verá algo como https:// ou até mesmo um ícone de cadeado.
Amplamente usado na internet, o HTTPS - Protocolo Seguro de Transferência de Hipertexto - (Hypertext Transfer Protocol Secure, em inglês) possibilita o envio e recebimento de informações entre dois sistemas de forma protegida. Ele é o sucessor do Protocolo de Transferência de Hipertexto, o HTTP, porém com foco em uma maior segurança, já que utiliza meios de criptografia para o tráfego de dados na rede.
Devido a essas características, ele é empregado no desenvolvimento de APIs, fornecendo métodos e status (ainda abordados no artigo) que permitem uma comunicação segura, simples e semântica entre aplicações.
Características de uma REST API
Para que desenvolvedores de software sigam um padrão na criação de interfaces de programação, existem arquiteturas de software que determinam algumas regras e boas práticas para a elaboração de uma API.
Uma dessas arquiteturas é conhecida como REST - Transferência Representacional de Estado - (*Representational State Transfer,* em inglês), e as APIs que seguem completamente as regras impostas por esse padrão são conhecidas como RESTful APIs. Elas devem possuir alguns princípios, como:
Interação Cliente-Servidor (Client-Server)
Um dos princípios mais importantes do desenvolvimento de APIs, mesmo daquelas que não seguem totalmente a arquitetura REST, é a interação entre clientes e servidores.
O cliente basicamente é um usuário ou aplicação que precisa solicitar uma informação. Já o servidor é uma aplicação que devolve ao cliente a informação solicitada. De forma simplificada, o cliente é quem faz uma requisição e o servidor é quem fornece uma resposta.
A API é a porta de entrada de um servidor, já que quando um cliente faz uma requisição, a API a recebe, faz a comunicação com o servidor e retorna a resposta do servidor para o cliente.
Uma das analogias mais famosas que facilitam a compreensão de uma API e do princípio cliente-servidor é a de um restaurante:
- O freguês é o cliente;
- O garçom é a API;
- O cozinheiro é o servidor.
Dessa maneira, é possível dividir as responsabilidades entre os sistemas, tornando-os independentes, além de simplificar a troca de dados na internet.
Estado Representacional (Representational State)
Ao seguir o princípio do Estado Representacional, uma API deve deixar explícito em sua URL os seus recursos. De forma simples, vamos supor que temos uma API que permite enviar e receber informações sobre livros.
Na sua URL, deve ser possível informar o que o cliente quer enviar ou receber, o que podemos chamar de recursos, que nesse caso são livros, e um identificador único de um dos meus recursos, nesse caso um código isbn, por exemplo, que é um código universal utilizado para identificar livros.
Dessa forma, a URL para recebermos informações sobre um determinado livro ficaria assim:
https://dominio.com/livro/9786555521368
Assim, conseguimos criar uma URL que representa um único recurso e todos que acessarem essa rota da API, receberão dados do livro com código 9786555521368.
Sem Estado (Stateless)
Esse princípio define que as solicitações realizadas pelos clientes aos servidores devem ser independentes, ou seja, cada “pedido” deve possuir todos os dados necessários para que o servidor possa processar a requisição do cliente, sem depender de informações de outras requisições realizadas anteriormente.
Dessa forma, as solicitações antigas não necessitam ser armazenadas pelo servidor, um comportamento conhecido como stateless, ou sem estado.
Interface Uniforme (Uniform Interface)
O princípio da interface uniforme determina que uma API precisa seguir um conjunto de regras consistentes para as suas operações. Para isso, é necessário o uso correto dos métodos e status HTTP, por exemplo, para estabelecer uma comunicação sólida entre o cliente e o servidor.
Por fim, é comum que clientes e servidores usem estruturas de dados como JSON ou XML para trocarem informações, sendo JSON um dos mais utilizados. Também chamado de “Notação de Objeto Javascript“ (JavaScript Object Notation, em inglês), O JSON possibilita o envio de dados de forma estruturada, como no exemplo abaixo:
{
"nome": "Fulano",
"sobrenome": "de Tal",
"idade": 20,
"endereco": {
"cidade": "São Paulo",
"uf": "SP"
}
}
Sistema em Camadas (Layered System)
Uma API é a porta de entrada do servidor, mas o servidor não necessariamente é formado exclusivamente por uma única aplicação. Os servidores podem ser divididos em camadas, cada uma com responsabilidades específicas, como realizar a autenticação do usuário, manipular o banco de dados ou se comunicar com outro serviço externo de terceiros, por exemplo.
Assim, o cliente não precisa saber da existência de toda uma complexa arquitetura de servidores, já que utilizando a interface de aplicação, a API, a comunicação com o servidor se torna simples, facilitando todo o processo de integração.
Legenda: Uma API é a porta de entrada do servidor, mas o servidor não necessariamente é formado exclusivamente por uma única aplicação. | Imagem: Freepik
Armazenamento em Cache (Cacheable)
Vamos supor que você é um usuário de um site que informa previsões do tempo. Essas informações da previsão do tempo, que estão gravadas no banco de dados do servidor do site de clima, geralmente não mudam consideravelmente a cada segundo ou pouco minutos, certo?
Será que faz sentido o servidor do site realizar uma consulta no banco de dados todas às vezes que o cliente solicitar a previsão do tempo? Em muitos casos não.
Para isso, é importante que as APIs possuam um armazenamento de dados em cache (um banco de dados em memória, na maioria dos casos), para que quando vários usuários solicitarem repetidas vezes a mesma informação em um curto espaço de tempo, os servidores não tenham que realizar sempre o mesmo processamento dessas requisições, que resultam sempre nas mesmas respostas.
Com isso, outra vantagem é a redução de interações entre os servidores e os bancos de dados, o que, além de reduzir custos, também melhora a performance das APIs, já que passam a responder com maior rapidez às solicitações dos clientes, proporcionando uma melhor experiência ao usuário, muitas das vezes, devido ao melhor desempenho das aplicações.
Código sob Demanda (Code On Demand)
Esse é um dos princípios opcionais de uma RESTful API, que define basicamente que uma interface de programação deve ser capaz de responder às solicitações de clientes com códigos executáveis, pelos quais os clientes mesmo serão responsáveis por executar, se necessário.
Atualmente o uso do código sob demanda é menos comum, mas já foi amplamente utilizado, principalmente para fornecer recursos adicionais para as funcionalidades dos navegadores de internet mais antigos.
Enfim, um dos motivos responsáveis pela diminuição do uso desse tipo de abordagem são as possíveis vulnerabilidades que determinados scripts podem causar, o que pode prejudicar a segurança dos usuários.
Métodos HTTP
Os métodos HTTP são responsáveis por facilitar a comunicação entre um cliente e o servidor, já que são eles que dão o sentido das ações que devem ser realizadas para determinado recurso em uma API. Existem vários métodos HTTP, mas os mais famosos e utilizados são esses:
POST
Utilizado pelo cliente para ENVIAR algum dado ao servidor.
GET
Utilizado pelo cliente para CONSULTAR algum dado do servidor.
PUT
Utilizado pelo cliente para ATUALIZAR COMPLETAMENTE algum dado no servidor.
PATCH
Utilizado pelo cliente para ATUALIZAR PARCIALMENTE algum dado no servidor.
DELETE
Utilizado pelo cliente para EXCLUIR algum dado no servidor.
Status HTTP
Em conjunto com os métodos HTTP, os status também são responsáveis por dar um significado para as respostas retornadas pelo servidor ao cliente. Eles são divididos em cinco grupos:
100-199
Os status entre 100 e 199 são responsáveis por indicar respostas informativas, como:
- 100 (Continue): representa que o cliente deve continuar a solicitação.
- 102 (Processing): representa que o servidor já está processando a solicitação.
200-299
Os status presentes entre 200 e 299 indicam que a comunicação do cliente com o servidor foi realizada com sucesso. Alguns exemplos de status dessa categoria são:
- 200 (OK): representa sucesso durante a consulta de algum dado pelo cliente no servidor.
- 201 (Created): representa sucesso durante o envio de algum dado pelo cliente ao servidor.
300-399
Os status que representam mensagem de redirecionamento da requisição estão entre 300 e 399, por exemplo:
- 300 (Multiples Choices): representa que a requisição pode ter mais que uma resposta.
- 301 (Moved Permanently): representa que a URL para qual a requisição foi realizada precisou ser alterada.
400-499
Os status que estão entre 400 e 499 indicam que a requisição foi realizada de maneira incorreta pelo cliente e alguns status são:
- 401 (Unauthorized): representa que as credenciais de autenticação que o cliente utilizou estão incorretas.
- 404 (Not Found): representa que o cliente solicitou ao servidor um dado que não existe.
500-599
Os status entre 500 e 599 mostram que ocorreu um erro no servidor. Dentre eles, podemos citar:
- 500 (Internal Server Error): representa que ocorreu um erro interno no servidor que ele não esperava que acontecesse.
- 501 (Not Implemented): representa que o método HTTP utilizado na requisição não está disponível no servidor.
Estes são apenas alguns exemplos dos diversos status HTTP existentes e que são fundamentais durante o desenvolvimento de uma API. Para conhecer outros, você pode consultar a documentação oficial da Mozilla para desenvolvedores.
Tipos de parâmetros
Existem diferentes formas para os clientes e servidores enviarem e receberem dados durante as requisições e respostas. Elas podem ser classificadas como:
Route Params
Também chamados de parâmetros de rota, eles compõem a rota da URL que o cliente fará requisição ao cliente. Lembra do exemplo do livro em que informamos o recurso `livros` e seu código universal? `https://dominio.com/livro/9786555521368`
Nesse exemplo, o cliente consegue enviar um dado ao servidor, no caso o código isbn, ao passar diretamente na rota.
Query Params
Conhecidos como parâmetros de consulta, eles também são informados na URL da requisição que o cliente faz ao servidor, mas de uma forma diferente dos route params. Quer um exemplo? Pesquise por algum animal no google.com
Você perceberá que será realizado uma requisição para a rota [google.com/search] e enviado na URL exatamente o que você quer consultar, neste caso gato.
Os query params são separados do restante da rota por um ponto de interrogação ? e os parâmetros de consulta enviados com o nome do parâmetro, seguido pelo sinal de igual e o valor, nesse caso, q=gato. Se necessário enviar mais de um parâmetro de consulta, é possível separá-los pelo caractere &. Exemplo: http://dominio.com/rota?param1=valor1¶m2=valor2
Body Params
Assim como explicado no princípio da Interface Uniforme da arquitetura REST, é possível enviarmos estruturas de dados como o JSON ou XML entre o cliente e o servidor. Esses dados são geralmente enviados como body params, também chamados de parâmetros do corpo da requisição.
Dessa forma, se um cliente quiser enviar os dados de um determinado livro para o servidor, ele poderia enviar as informações do livro de forma organizada no corpo da requisição.
POST https://dominio.com/livro
{
"livro": "Pequeno Príncipe",
"codigo": "9786555521368"
}
Utilizaremos uma ferramenta para nos ajudar a enviar os body params para o servidor, quando formos testar a API que desenvolveremos.
Headers
Os cabeçalhos HTTP, como também são chamados, são informações adicionais que o cliente e o servidor enviam um ao outro para tornar a comunicação mais precisa, com informações essenciais sobre os dados enviados ou recebidos em uma requisição, por exemplo.
Assim como os status HTTP, existem diversos tipos de cabeçalhos. Como exemplo, podemos citar:
- Content-Type: representa o tipo de conteúdo transportado nas requisições e respostas. Como exemplo, podem possuir os valores
text/htmlouapplication/json. - Content-Length: representa o tamanho do conteúdo transportado no corpo da requisição.
Você pode consultar a documentação oficial da Mozilla para desenvolvedores para conhecer os outros cabeçalhos HTTP.
Conclusão
Durante o artigo, abordamos o que é uma API e o que é o protocolo HTTP, seus métodos e status, além dos princípios da arquitetura REST, utilizada no desenvolvimento das interfaces de programação. Também vimos as diferentes formas que dados podem ser enviados e recebidos durante a comunicação entre o cliente e o servidor.
Dessa forma, vale lembrar que estes conceitos são úteis durante o desenvolvimento de APIs independente da linguagem de programação utilizada e você já pode colocá-los em prática quando for criar a sua própria interface de programação de aplicações.
Quer continuar a trocar ideias sobre Rest API? Me encontre no Fórum da Casa do Desenvolvedor, basta clicar no botão abaixo:
Texto originalmente postado neste link.
