Fundamentos Teóricos do REST

Webservices

O World Wide Web Consortium (W3C) define os web services como: aplicações cliente
servidor que se comunicam pela World Wide Web’s (WWW) através do protocolo HTTP
(HyperText Transfer Protocol) possibilitando a interoperabilidade entre softwares e
aplicações executando em uma grande variedade de plataformas e frameworks.
Caracterizam-se por sua grande interoperabilidade (capacidade de diversos sistemas
trabalharem em conjunto) e extensibilidade podendo ser combinados de forma baixamente
acoplada para executarem operações complexas. Programas proveem simples serviços que
podem interagir uns com os outros gerando soluções sofisticadas. Não sendo direcionado
para humanos e sim para outros programas.

Conceito REST

REST (Representational State Transfer, que significa Transferência Representacional de

Estado) é um modelo de arquitetura, que fornece diretrizes para que os sistemas
distribuídos se comuniquem diretamente usando os princípios e protocolos existentes da
Web sem a necessidade de SOAP ou outro protocolo sofisticado.

É baseada em um conjunto de constraints

1. Cliente-Servidor: Clientes e servidores separados.
2. Stateless server: O servidor não deve guardar o estado do cliente. Cada request de
um cliente contém todas as informações necessárias para atendê-la.
3. Cacheable: O cliente deve ser informado sobre as propriedades de cache de um
recurso para que possa decidir quando deve ou não utilizar cache.
4. Interface uniforme: Existe uma interface uniforme entre cliente e servidor:
Identificação de recursos (URI); Manipulação de recursos a partir de suas
representações; Mensagens auto descritivas; Hypermedia as the engine of
application state - HATEOAS
5. Sistema em camadas: Deve suportar conceitos como balanceamento de carga,
proxies e firewalls.
6. Código sob Demanda (opcional): O cliente pode solicitar o código do servidor e
executá-lo.

SOAP x REST
 SOAP REST

Protocolo de troca de mensagens em XML Um estilo arquitetural

Usa WSDL na comunicação entre cliente e servidor Usa XML, JSON etc. para enviar e receber dados

Invoca serviços através de chamadas de método Simplesmente chama serviços via URL PATH
RPC

Não retorna um resultado facilmente legível para Resultado legível por humanos já que é
humanos simplesmente JSON ou XML por exemplo

Comunicação feita por HTTP mas pode usar outros Comunicação feita unicamente por HTTP
protocolos como SMTP, FTP etc

Comparado com REST sua performance não é das Comparado com SOAP a performance é melhor
melhores consome menos recursos de processamento, código
mais enxuto etc

Request e Response

Podemos traduzir request como requisição, é o pedido que o cliente realiza para um
servidor. E o response vem da palavra resposta, depois que o client envia o request, o
servidor recebe e o processa. O resultado deste processamento é enviado como resposta.
O REST precisa que um cliente faça uma requisição para o servidor para enviar ou
modificar dados. Um requisição consiste em:
● Um verbo ou método HTTP, que define que tipo de operação o servidor vai realizar;
● Um header, com o cabeçalho da requisição que passa informações sobre a
requisição;
● Um path (caminho ou rota) para o servidor, como por exemplo
https://www.alura.com.br/artigos/golang-trabalhando-com-datas;
● Informação no corpo da requisição, sendo esta informação opcional.
Verbos HTTP

Os verbos HTTP são os métodos de requisição que utilizamos para acessar os endpoints
de uma RESTful API. Os métodos mais utilizados são:
● GET: recebe informação de um local;
● POST: envia informações para outro local;
● DELETE: deleta informações;
● PUT: edita/atualiza informações;
● PATCH: edita/modifica uma informação específica;

Exemplos:

Analogia com o SQL:

Parâmetros usados no REST

Os parâmetros da API são as partes variáveis ​de um recurso (rota). Eles determinam o tipo
de ação que deseja executar no recurso. Cada parâmetro tem um nome e tipo de valor.
Sempre que construir uma API REST ,deve decidir quais parâmetros devem estar presentes
nos endpoints da sua API . Em termos simples, os parâmetros da API são opções que
podem ser passadas com o terminal para influenciar a resposta.

Existem quatro tipos diferentes de parâmetros que geralmente são documentados e

utilizados na prática em uma API REST. São eles:

● Header Parameters - Ex.: sessionId: 258dsf5ad8d

Esses parâmetros são apresentados no cabeçalho da solicitação e geralmente estão
relacionados à autorização, como tokens, controle de sessão e dados de cookies.
Esse tipo de parâmetro aparece em qualquer método HTTP (GET, POST, PUT,
DELETE).

● Query Parameters - Ex.: /users?role=admin

Os parâmetros de consulta são o tipo de parâmetro mais comum. Eles aparecem no
final do URL de solicitação após um ponto de interrogação ( ?), com name=value.
Cada parâmetro desse tipo é separado por e comercial ( &). Os parâmetros de
consulta podem ser obrigatórios e opcionais. Além disso, eles não são únicos, no
sentido de que podem ser usados ​para especificar qualquer parâmetro várias vezes.

● Path Parameters - Ex.: /users/{id}

Os parâmetros de caminho são partes variáveis ​de um caminho de URL. Eles
geralmente são usados ​para apontar para um recurso específico dentro de uma
coleção, como um usuário identificado por ID. Um URL pode ter vários parâmetros
de caminho, cada um denotado por chaves { }.
 ● Body Parameters - Ex.: {"name": "Josias", "email": "josias@mail.com"}
Eles estão incluídos no corpo da solicitação e são usados ​para enviar e receber
dados por meio da API REST. É muito utilizado nas requisições PUT, e POST.

Status Codes

1×× Informacionais
2×× Sucesso
3×× Redirecionamento
4×× Erro de Client
5×× Erro de Server

HTTP Status Codes em Serviços REST:

● 200 OK – Request de criação ou deleção executada com sucesso.

● 201 Created – Criação de uma fila, tópico, fila temporária, tópico temporária,
session, producer, consumer, listener, queue browser ou mensagem realizada com
sucesso.
● 204 No Content – deleção de uma fila, tópico, sessão, producer ou listener bem
sucedida mas sem retorno de conteúdo.
● 400 Bad Request – O path informado está em um formato incorreto, um parâmetro
ou valor do corpo da requisição não está formatado corretamente ou um parâmetro
obrigatório não foi informado, ou está formatado corretamente mas pode estar
eventualmente inválido (por exemplo, o ID informado não existe –
NullPointerException, o conteúdo retornado é muito grande ou o ID informado já está
em uso).
● 401 Unauthorized – O cliente não tem autorização para executar requisições na
operação em questão.
● 403 Forbidden – O cliente não tem permissão para executar requisições na
operação em questão.
● 404 Not Found – o objeto requisitado pelo path não existe (NullPointerException ou
NullReferenceException).
● 405 Method Not Allowed – O usuário não tem permissão de acesso ao path.
● 409 Conflito – Foi feita uma tentativa de criar um objeto que já existe.
● 500 Internal Erro de Server – Ocorreu uma falha no servidor, podendo ser desde
uma falha no SQL por exemplo.

Nível de Maturidade de Richardson

Nível 0: O ponto de partida para o modelo é utilizar o HTTP como um sistema de transporte
para interações remotas, mas sem a utilização de qualquer um dos mecanismos da web.
Essencialmente, o que você está fazendo é usar HTTP como um mecanismo de
encapsulamento para o seu próprio mecanismo de interação remota. Exemplo:

Nível 1: Leva em consideração a utilização eficiente dos Endpoints tendo cada ação um
endpoint próprio. Esse é o primeiro passo para a glória do REST na RMM (Richardson
Maturity Model), nesse nível a utilização correta dos métodos HTTP ainda não é realizada.
O recurso pode ser entendido como uma entidade de negócio ou um substantivo da
aplicação. Exemplo:

Nível 2: leva em consideração a utilização eficiente dos endpoints (nível 1) e dos verbos
HTTP (nível 2). É importante também considerar que esse nível leva em consideração a
ótima utilização dos 9 verbos HTTP e também o retorno correto dos status codes de cada
endpoint após cada operação.
Nível 3: O último nível faz uma introdução a um assunto bem conhecido na área, referido
pela sigla HATEOAS (Hypertext As The Engine Of Application State). A implementação
deste nível fornece aos seus clientes links que indicarão como poderá ser feita a navegação
entre seus recursos. Quem for consumir a API precisará saber apenas a rota principal e a
resposta dessa requisição terá todas as demais rotas possíveis, facilitando o uso da sua
aplicação.

Glória do REST: A “Glória do Rest” é todo incremento além do terceiro nível, que visa a
melhor utilização da aplicação. Como por exemplo, a utilização de um link de uma Wiki
empresarial que retorna os erros de cada página com uma explicação sobre o tema,
simplificando assim a utilização da API após ter passado pelos níveis do REST.
HATEOAS

Hypertext As The Engine Of Application State é uma constante arquitetural de aplicações

REST. Uma API HATEOAS provê informações que permite navegar entre seus endpoint de
forma dinâmica, visto que inclui links juntos às respostas. Na prática as informações que os
consumers ou clients irão precisar para os próximos passos.

Documentação com Swagger

O swagger é um dos frameworks mais usados para documentar APIs Rest. Ele facilita para
que os desenvolvedores dos clientes que irão consumir as APIs saibam quais parâmetros
as operações suportam, qual o retorno, JSON, XML, CSV, binário, etc. Esse framework
valoriza muito as aplicações, virou um padrão para documentação de APIs.

Autenticação

Provê segurança na aplicação, utiliza o JWT (JSON Web Token). Como um Token de
Autenticação Funciona:
Anatomia de um JSON Web Token (JWT):

Versionamento

O REST foi projetado para suportar a evolução do projeto, melhor dizendo, de sua API.
Versionamento, quando se trata de APIs, é a capacidade de adicionar, remover, e modificar
funcionalidades sem mexer na interface e sem quebrar os seus clientes. Projetar uma API
que suporta mudanças é absolutamente fundamental, pois não temos controle sobre o que
acontece no mundo. As regras de negócio irão mudar o tempo inteiro e o sistema vai evoluir
constantemente. Umas das formas mais adotadas é o versionamento por URL, temos três
maneiras de fazer isso:

- Subdomínio: Você especifica a versão logo no início da URL, por exemplo:

HTTP GET
https://api-v1.minhagastronomia/vinhos

- Path: você especifica a versão após a base url, por exemplo:

HTTP GET
https://api.minhagastronomia/v1/vinhos
 - Query String: Essa é uma abordagem que já foi muito utilizada, mas que caiu em
desuso, pois além de prejudicar a navegação para outras versões, a legibilidade da
URL fica ruim em cenários de muitos parâmetros na query string.
HTTP GET
https://api.minhagastronomia/vinhos?version=1.0&pais=brasil

Boas Práticas

● Paginação;
● Filtros;
● Definir recursos lógicos;
● Tolerância a falhas;
● Cache;
● Conectividade;
● Timeouts;
● Documentação;
● Utilizar SSL;
● Versionamento;
● Teste e validação;
● Self-service;
● Exportações;
● I18n/Globalization;
● Notificações;
● Limite de campos;
● Selecionar a tecnologia adequada.

Feito por: Ester Gonçalves

Fontes Bibliográficas

http://www.semeru.com.br/blog/web-services/
http://www.semeru.com.br/blog/restful-web-services/
https://www.udemy.com/course/restful-apis-do-0-a-nuvem-com-springboot-e-docker
https://www.alura.com.br/artigos/rest-conceito-e-fundamentos
https://personal.ntu.edu.sg/ehchua/programming/webprogramming/HTTP_Basics.html
https://www.devmedia.com.br/rest-tutorial/28912
https://blog.mbeck.com.br/api-rest-e-os-verbos-http-46e189085e21
https://josiaspereira.com.br/tipos-de-parametros-em-requisicoes-rest/
https://blog.gft.com/br/2022/11/08/niveis-de-maturidade-de-richardson/
https://thiagolima.blog.br/parte-4-versionando-apis-restful-b1dd33c65a9c