HATEOAS

Guia de
Referência request
response
Rápida
headers

REST HTTP
URL
path
parameters

APIs query
parameters

2xx 3xx
Visão básica dos
principais status 4xx
codes
conceitos de 5xx
REST APIs
GET

verbos POST
PUT

Versionamento PATCH
Modelagem DELETE

Bounded
Context Segurança
Domain Driven
Design
Serviços
OpenId Connect
Entidades
verbos
OAuth 2.0
substantivos id

oliveira-michel.github.io
Por que REST API?
Guia de Referência Rápida

REST API
Assim como o inglês é tido como uma língua mais "padrão", o REST é tido como uma forma
de integração mais "padrão" do que as outras. Não significa que seja a melhor para todos os
cenários, mas é a mais popular, logo, amplamente suportada e conhecida pelo mercado,
linguagens e frameworks.

Multi dispositivos e Expõe seu negócio para

multicanal parceiros

O desenvolvedor escreve o Por se tratar de tecnologia

código uma única vez e ele padrão de mercado, permite
pode ser usado por vários conexão com parceiros para
dispositivos diferentes. criação de novos modelos de
negócio e inovação.

Agilidade
Facilmente encontrável
Negócios mudam mais
devagar do que seus clientes Analistas em novos projetos
e canais de venda. APIs conseguem encontrar as
permitem tirar lógica de funcionalidades já disponíveis
negócio dos canais de venda via APIs e sair usando.
tornando-os mais ágeis para
absorver as mudanças que o
mercado impõe.
Abstrai complexidade

Basta conectar um
1 Popularidade equipamento à tomada e ele
funciona sem que se conheça
O site detalhes da geração e
programmableweb.com, em transmissão da rede elétrica
2019, já listava mais de até a tomada.
22000 APIs públicas Da mesma forma, APIs
abstraem a complexidade dos
sistemas e expõe suas
funcionalidades em uma
É web
w interface simples e
ww
conhecida.
Por ser baseada no HTTP,
permite reaproveitar o
poder da infraestrutura
web já presente nas
empresas.

oliveira-michel.github.io
O que é?
É uma API que expõe estados de recursos e é implementada segundo um estilo Guia de Referência Rápida
arquitetural baseado no protocolo HTTP.
REST API

Application Programming Interface (API) Javascript Object Notation (JSON)

É uma interface para troca de É o formato {

dados entre sistemas. mais comum "nome": "José",
para trocar "idade": 34,
informações "altura": 1.53,
Tem um contrato muito bem
via API. "vip": true,
definido entre o provedor e o "endereco": null
consumidor. }

Hyper Text Transfer Protocol (HTTP)

É o protocolo da web que é composto de: As REST APIs são construídas utilizando-
- método (verbs) que indicam a ação a ser feita; se dos mesmos elementos do HTTP:
- endereço (URL) de um recurso na rede; expõem as informações em URLs, filtra
- parâmetros de entrada (query strings) com query strings, manipula-as através dos
- mensagem de request; verbos etc.
- mensagem de response;
- headers com informações de controle;
- body com mensagem de response.
Quer ver na prática?
Identifique as partes do protocolo em uma página no Chrome. Aperte Ctrl+Shift+I

parameters
URLs status codes body
verbs headers

Histórico
<xml/> REST
<SOAP/>

2000
2006 2010+
2000 2003 2003
Yahoo e Google lançam REST é adotado pelas
Roy Thomas Fielding, XML endereçando melhor Dispositivos móveis e
XML RPC APIs usando JSON/RPC maiores empresas de
um dos criadores do banda limitada sofrem e populariam o formato
estrutura, segurança e TI e se torna o
pouco HTTP, escreve
padrões trouxe vários para processar grandes de mensagem mais leve padrão mais
padronizado dissertação que cria o
frameworks mensagens XML que XML conhecido e usado
REST

oliveira-michel.github.io
Os 5 Princípios
O estilo arquitetural REST é definido por basicamente 5 princípios. Guia de Referência Rápida

REST API

Cliente
Preocupa-se com User Experience, Servidor é desacoplado do cliente.
Interface e múltiplos dispositivos.
Cliente / Não compartilham nenhum código
Servidor Servidor no mesmo processo.
Preocupa-se com performance,
autenticação, autorização, escala, Podem evoluir em paralelo
cache, armazenamento e segurança.

Recursos
HTTP/1.1 GET http://api.viagens.com/v1/destinos/14/opinioes
Representação dos recursos
{json} <XML/>
Interface Mensagens auto-descritivas: metadados
Uniforme HTTP Status Code, content-type, accept, host
Hypermedia
Contrato Dados + Ações (Hypermedia As The Engine Of Application State)

Não se armazena Cada requisição O cliente envia na

estado, sessão, vinda do cliente requisição toda a
nenhum dado é independente informação que o
Statelessness sobre uma da anterior. servidor necessita
requisição que já para processar a
aconteceu. requisição .

Compensa a perda de performance do

Statelessness, diminui a quantidade de
Cache local
API requisições e reduz tráfego na rede.
Caching Gateway

É controlado via headers cache-control,

expires, last-modified, Etag etc.
Cache Cache
Cache local
compartilhado compartilhado

Cada camada só tem acesso na

próxima.
API
Sistema de Gateway
Camadas Camadas podem ser adicionadas,
removidas ou modificadas
conforme necessidade.
X
oliveira-michel.github.io
 Recursos
São representações de coisas que existem no mundo real. Guia de Referência Rápida

REST API

Estado de um recurso
Alteração de estado

É o conjunto de atributos
Ex: Um veículo qualquer, se diferencia de outro
cujos valores representam o
por conta do conjunto de suas características
estado do recurso.
e normalmente uma delas é o identificador, pois
A proposta do REST é permitir
mesmo que as outras características mudem, o
as transferências, ou seja,
identificador nunca muda.
mudanças de estado dos
recursos.
Alteração de estado acontece quando uma ou
Exposição dos recursos mais características mudam.
{
Recursos são expostos "numeroDoChassi": "9BG114LW04C0001",
e representados via URL. As "ano": 2014, Hum ...
mudou o estado!
URLs devem ser definidas "marca": "GM", Maria Fernanda
"modelo": "Onix",
seguindo algumas boas práticas.
"proprietario": "José da Silva"
}

Exemplos

http://api.walmartlabs.com/v1/items/12417832

base path recursos

https://api.instagram.com/v1/users/{user-id}/relationship
base path recursos

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}
/providers/Microsoft.DBforMySQL/servers/{serverName}
/databases/{databaseName}

Boas práticas

substantivos Use substantivos, não verbos Cliente(s) Use plurais Versione seus
verbos GET /clientes não /listarClientes > Todos os clientes: /clientes
/v2/ contratos na URL
> Cliente específico: /clientes/007 GET /v1/pagamentos

Organize seus recursos em Mantenha o case consistente Tenha um domínio

estruturas hierárquicas Aa-B Escolha camelCase, PascalCase, kebab-case
www separado do site
Ex: ordens contém produtos ou snake_case para os atributos e https://api.twitter.com
GET /ordens/18953/produtos/1 parâmetros. https://api.walmartlabs.com
Prefira kebab-case nas URLs
(alguns servidores ignoram o case)

oliveira-michel.github.io
Verbos
Vêem do HTTP e indicam ao servidor qual ação (CRUD) deve ser aplicada um um Guia de Referência Rápida
determinado recurso representado por uma URL.
REST API

Podem ser seguros, quando não Inseguro

provocam mudança de estado no
Idempotente PUT
Não usa cache
servidor.
Modifica completamente a instância
Podem ser idempotentes, quando "n" de um recurso, fazendo substituição.
requisições iguais provocam o mesmo Request:
resultado no estado do recurso. PUT /usuarios/abc123
{“nome”: “Alguém mudou de nome”,
“e-mail”: “[email protected]”}

Inseguro Response:
POST Não idempotente HTTP 200 - Ok
Não usa cache
Caso a instância não exista, ele cria.
Solicita a criação de uma nova
instância de um recurso.
Inseguro
Request: Idempotente PATCH
POST http://api.com/usuarios Não usa cache
{“nome”: “Alguém”,
“e-mail”: “[email protected]”} Modifica parcialmente um recurso.
Response:
HTTP 201 - Created Request:
Location: /usuarios/abc123 PATCH /usuarios/abc123
{“nome”: “Alguém mudou só o nome”}

Response:
Seguro HTTP 200 - Ok
GET Idempotente
Pode usar cache
Inseguro
Solicita a representação de uma ou
Idempotente DELETE
Não usa cache
mais instâncias do recurso.
Apaga uma ou mais instâncias do
Request:
recurso.
GET /usuarios/abc123
Request:
Response:
DELETE http://api.com/usuários/abc123
HTTP 200 - Ok
{"id”: “abc123”, “nome”: “Alguém”,
Response:
“e-mail”: “[email protected]”}
HTTP 204 - No Content

Cenários "não CRUD"

Pouco usados Em alguns casos sem característica de CRUD,
os recursos representarão uma ação e usa-se
OPTIONS para listar os verbos possíveis para POST ou GET conforme característica de
um recurso segurança e idempotência. Ex:
HEAD para retornar apenas os cabeçalhos
TRACE para responder de volta o que o servidor
recebeu POST /email/123/enviar
GET /somar?a=18&b=77
oliveira-michel.github.io
Códigos de retorno
Vêem do HTTP e indicam o sucesso ou insucesso no processamento da requisição enviada Guia de Referência Rápida
ao servidor.
REST API
Existem muitos códigos de retorno (status codes) no HTTP. Para o REST,
alguns são amplamente adotados, outros menos. Seguem alguns dos principais:

1xx - Informação 4xx - Erro do cliente

Tem pouco ou nenhum uso com REST. Servidor não consegue entender a
400 Bad Request requisição, pois existe algum
parâmetro inválido ou falta dele
2xx - Sucesso
401 Unauthorized Credenciais inválidas
Credenciais válidas, mas sem
200 Ok Requisição processada com sucesso 403 Forbidden
acesso no recurso
201 Created Uma nova instância foi criada O servidor não encontrou o recurso
404 Not Found solicitado pelo cliente através da
O recurso será atualizado/criado de
202 Accepted URL
forma assíncrona
O recurso (URL) não existe mais e
A requisição foi processada com sucesso 410 Gone
204 No Content esta condição é permanente
e não há body na resposta
A requisição está correta ao nível
O servidor encontrou uma uma grande de parâmetros, mas existem erros
206 Partial Content quantidade de registros na resposta e 422 Unprocessable Entity
ao nível de negócio que impedem
devolveu de forma paginada o processamento da requisição

3xx - Redirecionamento 5xx - Erro do servidor

O recurso foi definitivamente Erro mais genérico para informar

301 Moved Permanently movido para uma outra URL definida 500 Internal Server que o servidor encontrou um cenário
no header Location Error inesperado de erro que não soube
consegue processar a requisição
O recurso foi definitivamente
303 See Other movido para uma outra URL O servidor não está respondendo
definida no header Location porque está fora do ar, em
503 Service Unavailable
manutenção ou sobrecarregado.
Redirecionamento de uma página
É um problema temporário
para outro endereço, porém que é
307 Temporary redirect com caráter temporário. O servidor, enquanto atuando como
Provavelmente por conta de alguma 504 Gateway Timeout gateway ou proxy, não conseguiu
manutenção no sistema responder em tempo

Mais informações sobre o retorno

{
Para os casos de "code": "10023",
"message": "Alguns campos estão preenchidos incorretamente.",
sucesso, o retorno da "details": "https://developer.empresa.com/apis/erros/10023",
requisição é o próprio "fields":[
{
recurso solicitdado. "name": "dataPedido",
"message": "O formato de data é inválido. Utilize data no padrão yyyy-MM-DD.",
Para os casos de erro, é "value": "01-05-2019",
"details": "https://developer.empresa.com/apis/erros/err-gen-086"
importante devolver um },
conteúdo, {
"name": "valorPagamento",
preferencialmente "message": "Valor não é number.",
padronizado, com mais "value": "R$ 27.568,90",
"details": "https://developer.empresa.com/apis/erros/err-gen-073"
detalhes sobre o }
problema. ]
}

oliveira-michel.github.io
Fluxo da requisição
Uma requisição e resposta em REST segue basicamente o funcionamento do protocolo Guia de Referência Rápida
HTTP.
REST API

Request

Informações do
remetente
Conteúdo da
Requisição: mensagem
relacionada ao
body recurso.

Endereço na rede do
Remetente: headers recurso sobre o qual se
Indica a ação a ser trata a requisição.
Destinatário: URL
aplicada em um Filtra indicando o
recurso: Complemento: query strings Indica o tipo de conteúdo
resultado
- Get + headers (representação),
esperado.
- Post + verbo informações de
- Put/Patch segurança e metadados
- Delete sobre a mensagem

Processamento

Servidor define uma Servidor que responde no Servidor altera o

representação para o endereço onde está o estado do
retorno (JSON, por recurso (URL) interpreta recurso no
exemplo) e monta uma a mensagem, valida e repositório.
mensagem de retorno. aplica as regras do
software.
<xml/> {json} PDF JPG

Response

O servidor pode
adicionar headers com
informações sobre a
resposta. Response:

body

headers O servidor informa o sucesso

ou insucesso do processamento
200 da requisição através de um
status code.

oliveira-michel.github.io
Requisições assíncronas
Algumas mudanças de estado dos recursos podem não ser processadas imediatamente. Guia de Referência Rápida
Para isso, um fluxo para acompanhar o processamento se faz necessário.
REST API
1 Requisição para um recurso que demora para ser processado

Request:
POST /pintinhos
{
"nome": "Amarelinho",
"papai": "Sr. Crista",
"mamae": "Dona Carijó"
}

3 Consultas ao novo recurso para

verificar o andamento
4
2 Resposta indicando o encaminhamento
5
para um novo recurso ?
...
Response:
HTTP 202 Accepted
Location: /ovinhos/59637

Request:
6 Consulta ao novo recurso para GET /ovinhos/59637
verificar o andamento
Response:
HTTP 200 Ok
! {
"id": 59637,
"situacao": "chocando",
"temperatura": 30,
"TTC": 2019-07-16T19:20:30.00-03:00,
"mensagens": [{
"codigo": "103",
"mensagem" : "Segundo o veterinário, tudo ok.",
"tipo": "info"
Request: }]
GET /ovinhos/59637 }

Response:
HTTP 303 See Other
{
"id": 59637, 7 Consulta ao novo recurso criado
"situacao": "nasceu",
"temperatura": null, Request:
"TTC": null
"mensagens": [] :) GET /pintinhos/2368

Response:
}
HTTP 200 Ok
Location: /ovinhos/59637 {
Content-Location: /pintinhos/2368 "id": 2368,
"nome": "Amarelinho",

!
"papai": "Sr. Crista",
O fluxo descrito se chama pooling, alternativamente, ao "mamae": "Dona Carijó",
solicitar a criação do "Amarelinho", o "Sr. Crista" poderia "idade": 1
informar seu endereço e quando o "Amarelinho" nascesse, }
ele receberia a informação o "Amarelinho" diretamente no
seu endereço. Este processo é o que chamamos de Call
Back.

oliveira-michel.github.io
Query strings
Presentes na URL, é um conjunto de 'chave=valor' que inicia com o caractere '?' e são Guia de Referência Rápida
separados por '&'. Normalmente indicarão filtros.
REST API
Alguns comportamentos se repetem em praticamente
todas as APIs, por isso, alguns padrões para as query Para pesquisas em qualquer atributo,
strings podem ser convencionados e adotados por todos é possível usar a "forma Google" de
os sistemas da empresa. pesquisar.

Isso reduz a curva de aprendizado do cliente e permite GET /aeroportos/GRU/restaurantes?q=vegano

que alguns códigos possam ser reusados.
GET /vestuarios?q=algodao

Em um GET, é possível filtrar as instâncias a serem

retornadas usando seus atributos. Alguns recursos que
retornam uma quantidade
GET /usuarios?signo=sargitario&signo=escorpiao&estadoCivil=solteiro maior de instâncias podem ter
seus resultados paginados.
GET /aeroportos/GRU/restaurantes?tipo=japones&faixaPreco=$$
GET /clientes?page=2&limit=50

Quando se pesquisa intervalos, pode-se utilizar

um 'from' 'to'. Para limitar a quantidade de
registros, pode-se utilizar o 'top'.
GET /clientes?fromIdade=21&toIdade=32
GET /ofertas-noturnas?top=3
GET /cartoes/3/faturas?fromDataVencimento=2020-10

Ordenação pode ser feita com uma estrutura de sort. Você pode devolver respostas
parciais dos recursos que têm muitos
sort=[{atributo}:{asc|desc}] atributos.

GET /ofertas-noturnas?sort=porcentagemDesconto,data:desc GET /clientes/123?fields=nome,idade

200 Ok
{ "nome": "José", "idade": 34 }
Para aninhar mais de uma requisição, use um 'expand'.

GET /cartoes/123
E se um determinado conjunto de
+ GET /cartoes/123/faturas/18
atributos é sempre requisitado, pode-
= GET /cartoes/123?expand=faturas&faturas.id=18 se definir "views".
200 Ok
{ "id": 123, GET /clientes/123?view=contatos
200 Ok
"numero": "5436 **** **** 3658",
{ "nome": "José",
"faturas"= [
{ "email": "@",
"endereco": "Rua A",
"id": 18,
"telefone": "912345678" }
"vencimento": 2020-06-18,
"valor": 2365.48
}
]
} Pode usar todos juntos? Sim!

oliveira-michel.github.io
HATEOAS
Hypermedia As The Engine Of Application State é capacidade pela qual um cliente pode Guia de Referência Rápida
interagir com a API através de links informados pelo servidor.
REST API

Como funciona

Em cada resposta da API, ela deve prover links que permitam que o cliente descubra todas
as possibilidades de alteração do estado de um recurso à partir do estado atual.

Request:
POST /consultas
{
"idMedico": "antonio59", Richardson Maturity Model
"inicio": "14:00",
"fim": "14:30",
"idPaciente": "jose85" Glory of
}
REST
Response:
HTTP 201 Created
{ Controle de
"data": { Hipermedia
"id": "123",
"idMedico": "antonio59",
"inicio": "14:00", Verbos HTTP
"fim": "14:30",
"idPaciente": "jose85"
},
"links":[ Recursos
{"rel": "self",
"href": "/consultas/123",
"title": "Esta consulta",
"method": "GET"}, Pântano de POX
{"rel": "cancelar",
"href": "/consultas/123",
"title": "Cancelar consulta",
"method": "DELETE"},
Leonard Richardson, autor de um
{"rel": "alterar", dos primeiros grandes livros de
"href": "/consultas/123", REST criou um modelo de
"title": "Alterar horário desta consulta",
"method": "PATCH"},
maturidade que representa os
{"rel": "agendamentos-medico", passos para a adoção das práticas
"href": "/medicos/antonio59/consultas", REST.
"title": "Listar consultas para o médico",
"method": "GET"},
{"rel": "agendamentos-paciente", Ele percorre desde o pântano de
"href": "/consultas?paciente=jose85", Plain Old XML (POX), quando não
"title": "Listar consultas do paciente", haviam padrões para troca de
"method": "GET"}
] mensagens, passa por separar bem
} os recursos em URLs, usar
corretamente os verbos do HTTP e
códigos de resposta e por fim, o
uso de HATEOAS.

Muitos dos sistemas não adotaram

o uso e descoberta das APIs via
HATEOAS.

oliveira-michel.github.io
Modelagem
É o processo de entender a demanda de negócio e transformá-la em recursos expostos Guia de Referência Rápida
via URL respeitando os padrões arquiteturais e regras do REST.
REST API

KISS (Keep It Simple, Stupid) Granularidade

Busque no máximo 2 níveis no

Modele suas APIs pensando nos seus
aninhamento de atributos.
clientes (desenvolvedores), não nos
seus dados. {
"id": 123,
Evite entregar mais de uma forma de "nome": "José",
fazer a mesma coisa. "dataNascimento": "1985-01-01",
"endereco": {
"logradouro": "Rua Feliz"
Foque nos casos principais primeiro, "numero": "10"
lide com as exceções depois. "complemento": "casa 2"
"CEP": "10000100"
}
Mantenha padrões. }

Domain Driven Design Passo-a-passo

O DDD fornece um conjunto de recursos, padrões e
práticas que ajudam a documentar e modelar Listar os requisitos
software. Entender o negócio sobre o qual o Ter a lista de funções do negócio que
software trata é essencial para se criar boas APIs. serão expostas via API.

Linguagem ubíqua Identificar as entidades

É o uso da linguagem falada que seja de Entender com os especialistas de negócio
conhecimento comum entre todos os como ele funciona e identificar os
envolvidos com um conceito de negócio: substantivos que representas as
o jargão. Um conceito de negócio deve entidades.
ter um nome único e seu significado
deve ser claro para todos. Identificar os serviços
Domain Model Identificar funções do negócio que não
são entidades através dos verbos que
É uma representação de conceitos do aparecem na conversa: processar, faturar,
mundo real (do negócio) que são reservar etc.
pertinentes ao um ou mais domínios a
serem trabalhados em um software. Fazer o Domain Model
Estes conceitos incluem as entidades,
Desenhar as entidades, serviços,
serviços e as relações entre eles.
relacionamentos e bounded contexts e
entidade = substantivos + ID alinhar o desenho com os especialistas do
serviços = verbos negócio para garantir que o entendimento
de tudo foi correto.
Bounded Context
Converter o Domain Model em REST
São fronteiras que separam conceitos Converter as entidades aninhando-as em
que têm alguma relação entre si. O URLs.
significado desta fronteira deve ser Converter os serviços CRUD nos verbos
claro para todo o time. Um bounded HTTP.
context pode inspirar divisões para
softwares diferentes, contratos de Definir os atributos de entrada e saída.
APIs, componentes etc.
Definir os códigos HTTP a serem
retornados.
oliveira-michel.github.io
Contrato
As URLs e os parâmetros de entrada e saída da API podem ser documentados em Guia de Referência Rápida
linguagens próprias pra isso. Esta documentação é chamada de contrato.
REST API

Contract First
Exemplo
Trabalhar em produzir um bom contrato de
API antes de começar o desenvolvimento do
código: openapi: 3.0.0
info:
title: Sample API
- faz com que muitas dúvidas apareçam e description: Sample API documentation.
sejam sanadas com antecedência; version: 0.1.9
servers:
- url: http://api.example.com/v1
- traz um entendimento mais completo do description: Main (production) server
negócio; - url: http://staging-api.example.com
description: Internal staging server for testing
paths:
- evita impedimentos e retrabalho durante o /users:
desenvolvimento; get:
summary: Returns a list of users.
responses:
- permite que o cliente possa adiantar o '200': # status code
desenvolvimento antes da API estar pronta. description: A JSON array of user names
content:
application/json:
O contrato, que contém cada item presente schema:
nas REST APIs , como URLs, path parameters, type: array
items:
query parameters, headers etc., assim como type: string
descrições e exemplos, pode ser utilizado /users/{userId}:
para: get:
summary: Returns a user by ID.
parameters:
- geração de código fonte para implementação - name: userId
em diversas linguagens; in: path
required: true
description: User Identification.
- geração de documentação web publicável, schema:
type : integer
navegável e que é capaz de fazer chamas às format: int64
APIs; minimum: 1
responses:
'200':
- configuração de API Gateways; description: OK

- configuração de testes automatizados;

Ferramentas
- etc.

Open API Specification

Antes conhecido como Swagger Specification,
o OAS é um formato para documentar REST
APIs.

A especificação permite que o documento seja

escrito em JSON ou YAML.
- stoplight.io/studio
Mais informações - editor.swagger.io
- github.com/42Crunch/vscode-openapi
https://swagger.io/docs/specification/about/

https://github.com/OAI/OpenAPI-Specification/blob
/master/versions/3.0.2.md

oliveira-michel.github.io
Versionamento
Mais de uma versão de API pode existir ao mesmo tempo, visando manter Guia de Referência Rápida
compatibilidade com os clientes antigos.
REST API

"A única coisa que não muda é que tudo muda."

Heráclito, Filósofo

Quebra de contrato Alteração de contrato

Acontece quando uma alteração na Acontece quando uma alteração na

estrutura da API gera erro no cliente caso estrutura da API não gera erro no cliente
ele se mantenha chamando a API da caso ele se mantenha chamando a API da
mesma forma. mesma forma.

X Remoção de atributos de resposta. V Adição de atributos de resposta.

X Adição de atributos, headers, query V Adição de atributos, headers, query

parameters etc. obrigatórios na parameters etc. não obrigatórios na
requisição. requisição.

X Remoção de recursos (URLs). V Adição de recursos (URLs).

X Alteração de atributos, headers, V Quando se tem um documento da

query parameters, URLs etc. especificação da API, altera alguma
obrigatórios ou não. descrição ou exemplo.

Semantic Versioning Estratégia de migração

1 - Todos os clientes na v1
Ao alterar o documento do contrato da
API, é interessante adotar o
versionamento semântico para controlar o
artefato. 2 - A v1 faz proxy
Incrementa ao para a implementação
2 . 3 . 1 fazer ajustes que
não alteram
da v2. Os clientes são
major.minor.patch tecnicamente o /v1/ solicitados para
contrato, como migrar para a v2.
exemplos,
descrições etc.
3 - Todos os clientes
migraram para a v2.
Incrementa ao
fazer ajustes que Incrementa ao fazer A v1 é desligada.
alteram ajustes que alteram
tecnicamente o tecnicamente o
contrato e contrato sem causar
causam erro no erro no cliente que /v1/ /v2/
cliente que já usa. já usa.

http://api.com/vendas/v2 X
/v1/ /v2/

oliveira-michel.github.io
OpenID Connect e OAuth 2.0
OpenID Connect é uma camada de identificação do usuário que roda sobre o OAuth 2.0. Guia de Referência Rápida
O OAuth 2.0 é um padrão para autorizar acessos sem ficar trafegando senhas.
REST API

OpenId Connect

Permite que o sistema A acesse o sistema B em nome do cliente sem que o sistema A tenha
acesso às credenciais do cliente (login e senha). A requisição de acesso gera um token e
este token pode ser revogado por vontade do cliente diretamente no sistema B.

Loja Online Cliente Rede Social

(Resource Server) (Resource Owner) (Authorization Server)

Pede para logar via Rede Social

Solicita tela de login da Rede Social e informa URL de Callback
Mostra tela de login

Cliente preenche credenciais

e autoriza a Loja Online
a acessar os dados
Rede Social devolve token para a Loja Online
Loja Online acessa recursos da APIs da rede Social
em nome do cliente usando o token

OAuth 2.0

Exemplo de fluxo Client Credentials do OAuth 2.0. O Sistema de Vendas não conhece as
credenciais do Sistema Cliente da API e confia no Security Token Service para validar o
token.

Sistema credenciais Security Token Em caso de

/oauth
Cliente da API token Service token inválido
para uma
determinada
REST API, os
API sistemas
token válido? token válido?
Gateway retornam um
HTTP 401
Unauthorized
token + dados da requisição /ofertas Sistema de ou 403
/vendas dados Vendas
dados de retorno de Forbidden.
retorno

oliveira-michel.github.io