Aplicações de softwares que trabalham com interoperabilidade entre aplicações de alto desempenho precisam que essas consultas sejam realizadas de forma rápida e segura. A abstração de arquitetura de software API REST é a mais indicada na construção desses modelos de negócios.
API REST oferece um conjunto de rotinas e padrões estabelecidos para o desenvolvimento de aplicações robustas e de fácil criação, disponibilizando recursos de consumo de dados sem comprometer as regras de negócio da aplicação.
Pronto para conhecer mais sobre esse artigo? Então, confira o que falaremos a seguir:
- O que é API REST?
- Qual a relação entre HTTP e REST?
- Entenda as diferenças entre SOAP e REST
- Para que serve o API REST? Principais aplicações!
- Quais os tipos de API REST?
- O que é o Richardson Maturity Model?
- Entenda a importância do REST API!
- Quais as vantagens e desvantagens de usar API REST?
- Quais as diferenças entre API REST e API RESTFUL?
- Confira um exemplo de API rest e entenda na prática!
- Construindo uma API REST na prática: o passo a passo!
- Boas práticas para usar com API REST!
O que é API REST?
Para entendermos o que é API REST, vamos inicialmente explicitar o conceito de API.
O acrônimo API é a abreviação de Application Programming Interface, que significa “Interface de Programação de Aplicações”. Representa um conjunto de rotinas e padrões estabelecidos e documentados para que uma determinada aplicação de software tenha autorização para utilizar as funcionalidades oferecidas por essa aplicação, sem precisar conhecer as anuências dessa implementação.
Isso garante segurança de código e, principalmente, das regras de negócio do software e a interoperabilidade entre aplicações, em que essa comunicação ocorra utilizando as requisições HTTP responsáveis pelas operações de manipulação de dados.
API REST é uma abstração de arquitetura de software que fornece dados em um formato padronizado para modelos de requisições HTTP.
Por exemplo, sites em WordPress podem conter plugins que acessam páginas de redes sociais para tornar a interação com o conteúdo mais atrativa e interativa. Quando uma pessoa usuária clica na interação “curtir”, automaticamente uma chamada API é realizada para concluir essa ação. Isso é possível porque as redes sociais disponibilizam um token com prévia autorização para que esses sites consigam interagir de forma assíncrona.
Conheça a arquitetura REST e seus princípios!
A arquitetura REST possui um conjunto de regras e princípios que devem ser seguidos. Vamos conhecê-los:
Cliente-Servidor: Trata a respeito da separação de responsabilidades, ou seja, separar as preocupações de interface do usuário (User Interface) do banco de dados, abstraindo a dependência entre os lados clientes/servidor e permitindo a evolução desses componentes sem impacto e quebra de contrato.
Interface Uniforme: É a interoperabilidade entre os componentes cliente e servidor. Como o cliente e servidor compartilham da mesma interface, é necessário estabelecer um contrato para a comunicação entre essas partes. Para isso, há quatro princípios a serem seguidos:
1) Identificação dos recursos (por exemplo,Swagger);
2) Representação dos recursos;
3) Mensagens auto-descritivas;
4) Componente HATEOAS.
Stateless: Cada requisição acionada entre a comunicação cliente-servidor deve possuir toda a informação necessária e compreensível para realizar a origem da requisição, não sendo de responsabilidade do servidor armazenar qualquer tipo de contexto. Isso pode gerar alto tráfego de dados e impacto na performance da aplicação, porém pode-se utilizar recursos de cache nesses casos.
Cache: É utilizado para melhorar a performance de comunicação entre aplicações, otimizando o tempo de resposta na comunicação entre cliente-servidor. É de responsabilidade do servidor controlar as diretivas de cache através do cabeçalho HTTP (HTTP Header).
Camadas: A separação de responsabilidades é importante nesse modelo de arquitetura. Os princípios e as boas práticas na arquitetura e design de um projeto, sugerem a construção de camadas independentes e auto gerenciadas, em que cada camada não pode conhecer as demais camadas. Caso ocorra mudanças em uma delas, as demais não serão impactadas. Nesse modelo, o cliente não deve conectar-se diretamente ao servidor da aplicação, porém uma camada de balanceamento de carga deverá ser acionada para essa responsabilidade.
Qual a relação entre HTTP e REST?
No estilo arquitetural REST, a manipulação dos recursos disponibilizados para o cliente é realizada através de métodos do protocolo HTTP.
Os métodos HTTP indicam os diferentes tipos de operações que o cliente pode realizar para manipular os dados através de requisições para cada contrato oferecido.
Em geral, os contratos representam as operações CRUD, porém há outros métodos HTTP que podem ser oferecidos para o cliente consumir.
É importante considerar que os métodos HTTP precisam identificar suas rotas e ações de forma clara e entendível, vejamos os exemplos a seguir:
Conheça os métodos HTTP mais utilizados e seus significados:
| Verbo HTTP | Descrição | Resposta | |
| POST | É utilizado para criar um novo registro no banco de dados. | Status Code 201 – registro criado | |
| GET | É utilizado para ler registros no banco de dados. | Status Code 200 – retorna os registros no formato solicitado. | |
| PUT | É utilizado para atualizar um registro no banco de dados. | Status Code 200 – registro atualizado. | |
| PATCH | É utilizado para atualizar parte de um registro no banco de dados. | Status Code 200 – registro atualizado. | |
| DELETE | É utilizado para deletar um registro no banco de dados. | Status Code 204 – registro deletado. | |
Entenda as diferenças entre SOAP e REST
Enquanto no estilo arquitetural REST, a implementação dos recursos é rápida, prática e acessível, no protocolo SOAP vamos encontrar regras que desaceleram a sua utilização.
O acrônimo SOAP é a abreviação de “Simple Object Access Protocol”, significa protocolo de acesso a objetos simples, é utilizado para possibilitar a comunicação entre aplicações distintas, não importando em qual linguagem de programação elas tenham sido desenvolvidas. Para esta comunicação ocorrer, esse protocolo estabelece regras integradas que aumentam a sua complexidade e impactam no tempo de retorno dos dados.
No estilo arquitetural REST, toda a comunicação é realizada através de endpoints oferecidos para que outras aplicações, utilizando token para a segurança no acesso e manipulação dos dados, consiga interagir com segurança utilizando os métodos HTTPs disponibilizados.
No protocolo SOAP, as requisições são enviadas através de serviços SMTP (e-mail), JMS (Java Message Server), HTTP (navegadores de web), TCP (protocolo de controle de transmissão), entre outros.
Para que serve o API REST? Principais aplicações!
API REST serve para a comunicação entre aplicações para estabelecer o consumo de informações de forma rápida e segura.
É utilizada para estruturar qualquer modelo de aplicações web para os dias atuais, onde temos um alto volume de trocas de dados sendo processados de forma assíncrona entre diversas aplicações. Conheça algumas delas:
- Redes sociais
- Sites de E-Commerce
- Internet das coisas
- Inteligência Artificial
- Aplicações executadas pelo próprio navegador (Web App)
- Aplicações Mobile
- Serviços de troca de mensagens (WhatsApp, Slack)
- Repositório de dados (Google Drive, GitHub, Azure Blob Storage)
Quais os tipos de API REST?
Utilizar API REST significa utilizar uma API para o consumo de dados em aplicações back-end, de modo que essa comunicação seja estabelecida utilizando padrões definidos no estilo arquitetural REST. Os três tipos de APIs são:
Privadas ou Locais
Modelo restritivo, utilizado entre aplicações internas de uma empresa, ou seja, local.
Geralmente são aplicações que disponibilizam acessos a dados mais críticos e sigilosos da empresa, em que o acesso a aplicações externas é bloqueado utilizando Proxy e sistema de autenticação de alto nível.
Parceiras ou baseadas em programa
Modelo restritivo, utilizado entre parceiros de negócios ou para a integração entre diferentes softwares de uma mesma empresa ou entre terceiros.
Nesse modelo, a autenticação de acesso aos dados é conhecida apenas entre as partes estabelecidas.
Públicas ou baseadas em web
Modelo que pode ser acessado praticamente por qualquer aplicação de software, mediante um pedido de requisição do tipo HTTP GET.
Uma das suas principais utilidades é na realização de testes de acesso ou validação de uma aplicação durante o seu desenvolvimento.
Conheça alguns modelos públicos de API REST:
· Nasa
· Marvel
· Football
· Youtube
· MovieDB
O que é o Richardson Maturity Model?
O acrônimo RMM conhecido como “Richardson Maturity Model”, significa um modelo de maturidade sugerido em 2008 por Leonard Richardson para classificar as APIs da Web, conforme sua aderência e conformidade para cada um dos quatro níveis do modelo.
Para isso, Richardson utilizou três fatores: URI, métodos HTTP e Hypermedia (HATEOAS). Um serviço é considerado maduro quando se emprega esses conceitos. Veja uma demonstração da hierarquia desses fatores:
As categorias que Richardson utilizou foram:
Level Zero Services: Nível zero de maturidade significa que uma determinada aplicação não utilizou os recursos de URI, métodos HTTP e Hypermedia (HATEOAS).
Level One Services: Nível um de maturidade considera a utilização eficiente de URIs. Os recursos são mapeados, porém não empregam com eficiência o uso dos verbos. Exemplos: métodos HTTP POST e HTTP GET.
Level Two Services: Nível dois de maturidade considera o uso eficiente de URIs e verbos HTTP.
Nesse nível, a API suporta os seguintes verbos HTTP:
– HTTP POST: utilizado para criar registro em banco de dados;
– HTTP GET: utilizado para a leitura de registros em banco de dados;
– HTTP PUT: utilizado para atualizar um determinado registro em banco de dados;
– HTTP PATCH: utilizado para atualizar parte de um determinado registro em banco de dados.
Level Three Services: Nível três de maturidade utiliza os fatores URI, HTTP e Hypermedia com eficiência. Os controles de hipermídia tem o objetivo de gerenciar o que pode ser feito, enquanto o URI do recurso ensina como manipulá-los.
Entenda a importância do REST API!
O crescente número de interações em redes sociais, o avanço da internet das coisas e a praticidade e segurança no consumo de dados entre distintas aplicações são os principais fatores que justificam a utilização do REST API para facilitar a comunicação entre esses sistemas.
REST API permite a criação de websites e aplicações em nuvem com maior rapidez e robustez, permitindo que os dados sejam acessados, criados e atualizados sincronizadamente, sem comprometer a integridade das informações.
Outro fator importante é a melhora significativa na qualidade e maturidade de software, pois quanto mais as aplicações interagem entre si para as trocas de informações, melhor será o resultado para as pessoas usuárias finais em suas tomadas de decisões.
Quais as vantagens e desvantagens de usar API REST?
API REST apresenta vantagens competitivas, porém também há desvantagens que precisam ser consideradas. São elas:
Vantagens
· Separação entre cliente-servidor
· Praticidade no acesso aos contratos da aplicação
· Confiabilidade e segurança na aplicação
· Escalabilidade para aplicações, principalmente nos modelos de microsserviços
· Multiplataforma, considerando que os dados podem retornar nos padrões XML e JSON
Desvantagens
· Conhecimento dos padrões de projeto para o modelo REST API
· Implementação “Lo-rest”, ou seja, desenvolver aplicações que disponibilizam apenas dois endpoints: HTTP GET e HTTP POST
· Trabalham de forma assíncrona, aumentando a sobrecarga das solicitações, podendo comprometer o desempenho da comunicação entre as aplicações
Quais as diferenças entre API REST e API RESTFUL?
API REST e API RESTFUL possuem objetivos distintos, mas complementares. A diferença encontra-se somente no cumprimento das exigências da arquitetura de software.
O estilo de arquitetura de uma API REST deve possuir alguns princípios:
· Não possui criptografia
· Não possui sessão
· Utiliza apenas o protocolo HTTP
· Os recursos devem ser acessados somente utilizando o protocolo de internet URI (Uniform Resource Identifier)
· O retorno dos dados devem ser nas formas mais conhecidas, exemplos: JSON e XML
API RESTFUL é o cumprimento de todos os princípios citados anteriormente, ou seja, um serviço baseado em REST é chamado de serviços RESTFUL, com o objetivo de oferecer uma excelente interatividade e rapidez na comunicação entre os serviços.
Confira um exemplo de API rest e entenda na prática!
Apresentamos o exemplo de consumo de uma API REST, onde a URI será “https://meusite.com.br”.
Os dados consultados pertencem à tabela Pessoa e seus atributos são: Id, Nome e Idade.
Vamos utilizar como retorno dos dados o padrão de formatação JSON.
1) HTTP GET
URI: https://meusite.com.br/api/pessoas
Definição: Retornar todos os dados cadastrados na tabela pessoa
Retorno dos dados:
{
"status":200,
"data":[
{
"id":1,
"nome":"Maria Santos",
"idade":20
},
{
"id":2,
"nome":"Sandro Pereira",
"idade":25
}
]
}2)HTTP GET
URI: https://meusite.com.br/api/pessoas/{id}
Definição: Retornar os dados cadastrados na tabela pessoa apenas do id informado
Retorno dos dados:
{
"status":200,
"data":[
{
"id":1,
"nome":"Maria Santos",
"idade":20
}
]
}3)HTTP POST
URI: https://meusite.com.br/api/pessoas
Definição: Criar um novo registro de dados na tabela pessoa.
Os campos obrigatórios devem ser informados no corpo da requisição
Corpo da requisição:
{
"nome":"Joana Marques",
"idade":32
}
Retorno dos dados:
{
"status": 201,
"success": true
}4) HTTP PUT
URI: https://meusite.com.br/api/pessoas
Definição: Atualizar um registro de dados na tabela pessoa. Os campos a serem
atualizados devem ser informados no corpo da requisição
Corpo da requisição:
{
"id":1,
"nome":"Maria Soares dos Santos",
"idade":21
}
Retorno dos dados:
{
"status":200,
"success": true
}5)HTTP PATCH
URI: https://meusite.com.br/api/pessoas/{id}
Definição: Atualizar apenas determinados campos de um registro na tabela pessoa.
Corpo da requisição:
{
"idade":23
}
Retorno dos dados:
{
"status":200,
"success": true
}
6) HTTP DELETE
URI: https://meusite.com.br/api/pessoas/{id}
Definição: Remover um registro na tabela pessoa.
Retorno dos dados:
{
"status":204
}Construindo uma API REST na prática: o passo a passo!
Nesse tutorial, vamos aprender a criar uma API REST utilizando a linguagem de programação C#, com base no framework gratuito .NET CORE.
Pré-Requisitos
- Editor de código: vamos utilizar a ferramenta gratuita de editor de código Visual Studio Community. O download pode ser realizado no portal da Microsoft.
- POSTMAN: os testes dos endpoints dessa aplicação serão realizados usando a ferramenta gratuita API Client Postman. O download pode ser realizado no site oficial Postman.com.
Criação do projeto API REST
1) Abra a ferramenta Visual Studio Community;
2) No menu Arquivo, clique na opção Novo e, em seguida, na opção Projeto:
3) Vamos criar o projeto do tipo API Web do ASP.NET Core, clique nessa opção conforme exemplo a seguir:
4) Em seguida, clique na opção Próximo, conforme exemplo a seguir:
5) A próxima ação é criar o nome do Projeto: ExemploAPI e, em seguida, clique na opção Próximo:
6) Precisamos adicionar informações sobre qual a versão do .NET CORE vamos utilizar. Configure essas informações conforme modelo abaixo e, em seguida, clique na opção Criar:
7) A estrutura do projeto terá essa apresentação:
8) A classe modelo que conterá as propriedades utilizadas para essa API será chamada de TodoItem. Para criar a pasta Models, clique com o botão direito no projeto ExemploAPI, em seguida, escolha a opção Adicionar e depois a opção Nova Pasta:
9) O resultado da criação da pasta deverá ser apresentado dessa forma:
10) Vamos criar a classe TodoItem. Clique com o botão direito na pasta Models. Em seguida, escolha a opção Adicionar, depois clique na opção Classe:
11) Para adicionar uma nova classe, digite no campo Nome: TodoItem, em seguida, clique na opção Adicionar:
12) O resultado apresentado será este:
13) Abra a classe TodoItem e digite as seguintes propriedades:
14) Para simular todas as ações da API REST, vamos utilizar o contexto de banco de dados chamado de Microsoft.EntityFrameworkCore.InMemory. Essa biblioteca executa todas as requisições utilizando o Mock dos dados.
Clique no Projeto ExemploAPI com o botão direito, escolha a opção Gerenciar Pacotes do NuGet:
15) No campo Procurar, digite o nome da biblioteca Microsoft.EntityFrameworkCore.InMemory. Em seguida, selecione essa biblioteca e clique na opção Instalar:
16) Para realizar a conexão com o banco de dados em memória, vamos criar a classe contexto, responsável pela configuração com a classe modelo.
Clique com o botão direito no projeto ExemploAPI, em seguida escolha a opção Adicionar e depois na opção Classe:
17) Para adicionar uma nova classe, digite no campo Nome: TodoContext, em seguida, clique na opção Adicionar:
18) O resultado apresentado será o seguinte:
19) Agora precisamos realizar a Injeção de Dependência do Contexto de Banco de Dados que acabamos de criar com o nome de TodoContext. Para isso, abra a classe com o nome de Startup.cs:
20) No método ConfigureServices, adicione a seguinte instrução:
services.AddDbContext<TodoContext>(opt =>
opt.UseInMemoryDatabase("TodoList"));
Agora vamos entender cada parte da instrução anterior:
- services: é o parâmetro do método ConfigureServices responsável em receber todas diretivas de serviços e bibliotecas para a Injeção de Dependência no projeto;
- AddDbContext<TodoContext>: significa que vamos adicionar a injeção de dependência do contexto TodoContext no projeto;
- opt.UseInMemoryDatabase(“TodoList”): significa que a injeção de dependência será do tipo Banco de Dados em Memória;
- “TodoList”: esse é o nome que criamos para o Banco de Dados em
Memória.
A classe Startup.cs deverá apresentar esse resultado:
21) Vamos criar um Controlador para as requisições referente a classe modelo TodoItem.
Clique com o botão direito na pasta Controller, em seguida escolha a opção Adicionar e depois clique na opção Controlador:
22) Escolha a opção Controlador MVC com exibições, usando o Entity Framework. Em seguida clique na opção Adicionar:
23) Configure as opções de Classe do Modelo e Classe de Contexto de Dados conforme exemplo a seguir. Em seguida, clique na opção Adicionar:
24) Adequar o Controlador conforme exemplo a seguir:
25) Clique na pasta Properties, abra o arquivo launchSettings, altere os valores de launchUrl, conforme exemplo a seguir:
26) Para executar a API REST, clique na opção IIS Express:
27) O navegador de internet será inicializado, apresentando o resultado:
28) Abrir o Postman para executarmos todas as requisições da API.
Vamos começar pelo endpoint POST. Digite a URI:
http://localhost:5000/api/todoitems/
Em seguida, clique no combo à esquerda da URI e escolha a opção POST.
Na aba Body, digite os valores Nome e Complete conforme exemplo a seguir.
Para simular a requisição, clique no botão Send:
29) O resultado esperado sempre será apresentado no campo inferior do Postman:
30) Para executar a requisição GET, realizar as configurações conforme exemplo a seguir, em seguida, clique na opção Send:
31) Para executar a requisição PUT, realizar as configurações conforme exemplo a seguir, em seguida, clique na opção Send:
32) Para executar a requisição DELETE, realizar as configurações conforme exemplo a seguir, em seguida, clique na opção Send:
Boas práticas para usar com API REST!
Conheça as boas práticas na utilização de API REST:
Organização da semântica dos serviços: uma boa semântica é quando esses serviços são de fácil leitura e compreensão. Exemplos:
| Boas práticas | Evitar |
| [GET] https://meusite.com.br/api/peoples | [GET] https://meusite.com.br/api/getAllPeoples |
| [GET] https://meusite.com.br/api/peoples/1 | [GET] https://meusite.com.br/api/getPeopleById |
| [POST] https://meusite.com.br/api/peoples | [POST] https://meusite.com.br/api/CreatePeople |
Verbos HTTP: utilizar corretamente os verbos HTTP, de acordo com suas definições e operações. Os verbos mais utilizados são:
– GET: Recupera informações de um recurso;
– POST: Cria um novo recurso;
– PUT: Atualiza um determinado recurso;
– DELETE: Remove um determinado recurso;
– PATCH: Atualiza parte de um determinado recurso.
HTTP Status Code: é o padrão utilizado para as respostas de cada solicitação de serviço utilizado. Para cada verbo HTTP, os retornos do status code seguem os seguintes padrões:
– HTTP GET: os retornos esperados são:
– 200 (OK): em caso de sucesso.
– 404 (not found): caso a entidade solicitada não seja encontrada.
– HTTP POST: os retornos esperados são:
– 201 (created): um novo recurso foi criado com sucesso.
– 400 (bad request): a requisição contém dados inválidos.
– 422 (unprocessable entity): a requisição violou alguma regra de negócio da aplicação.
– HTTP PUT: os retornos esperados são:
– 200 (OK): atualizado com sucesso.
– 400 (bad request): a requisição contém dados inválidos.
– 409 (conflit): não foi possível atualizar um recurso existente.
– HTTP DELETE: os retornos esperados são:
– 204 (not content): sucesso na remoção do recurso.
– 404 (not found): caso a entidade solicitada não seja encontrada.
Versionamento de API: permite maior controle na implementação dos endpoints, permitindo direcionar os clientes que utilizam esses serviços para os novos endpoints sem perda do contrato. Exemplos:
– URI: https://meusite.com.br/api/v1/pessoas
– Subdomínio: https://v1.meusite.com.br/api/pessoas
– Header: “Accept”=“application/meusite.api.v1.json”
– Querystring: https://meusite.com.br/api/pessoas?version=1.0
API REST é um estilo arquitetural que dinamiza as aplicações que necessitam trabalhar com interoperabilidade com outras aplicações na troca de dados, além de oferecer segurança e praticidade na sua implementação e manutenção.
Gostou do nosso artigo? Então, convidamos você para a leitura sobre DD/MM/AAAA, como formatar datas em diferentes linguagens de programação!
