REST: Padrões e Melhores Práticas

[ Empowering Business.
Architecting IT ]

1 © Copyright | www.sensedia.com

REST: Patterns & Best Practices


Quem somos nós

alessandro.oliveira@sensedia.com
@aro1976

felipe.firmo@sensedia.com
@felipe_firmo


Público Alvo

API Designer

Diretor Arquiteto

Gerente Programador


Agenda
• Sobre a Sensedia
• SOAP vs. REST
• Elegibilidade de REST
• Desafios de REST
• Padrões e Melhores Práticas REST
• Ferramentas
• Q&A


[ Sobre a
Sensedia ]

Nosso core é Arquitetura de TI:
Serviços & Ferramentas.

Ajudamos empresas a serem
Mais Ágeis, Flexíveis e Inovadoras

Crescimento consistente:
63% CAGR 2007-2011


[ Sobre a
Sensedia ]

Profundo conhecimento em:
√ SOA (Service Oriented Architechture)
√ Governança
√ Enterprise Architecture
√ Cloud Computing


[ Sobre a
Sensedia ]

Posicionado como Visionário no
Quadrante Mágico do Gartner(1)

Criada a partir de iniciativa conjunta
entre Ci&T e Laboratório de Inovação
da Unicamp.


[ Sobre a
Sensedia ]

Sede em Campinas, SP e escritórios em
São Paulo, SP e Philadelphia, EUA

Campinas, BR São Paulo, BR Philadelphia, EUA


[ Quem tem experimentado
a proposta de valor da Sensedia ]


SOAP vs. REST


SOAP vs. REST
• SOAP: Simple Object Access Protocol
• Baseado em XML
• Padronizado pelo W3C
• Soluções de diversos fabricantes
• Compatibilidade com diversas linguagens e plataformas
• Maior consumo de banda e complexidade na implementação
• Contratos fortemente tipados
• JSR 224: JavaTM API for XML-Based Web Services (JAX-WS) 2.0


Exemplo de Requisição SOAP
POST /Stock HTTP/1.1
Host: www.stockexchange.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 299
SOAPAction: "http://www.w3.org/2003/05/soap-envelope"

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header>
</soap:Header>
<soap:Body>
<m:GetStockPrice xmlns:m="http://www.stockexchange.org/stock">
<m:StockName>ORCL</m:StockName>
</m:GetStockPrice>
</soap:Body>
</soap:Envelope>

SOAP vs. REST
• REST: REpresentational State Transfer
• É um estilo arquitetural, portanto, não necessariamente
um PADRÃO
• Fortemente baseado na semantica do HTTP
 Operações: GET, POST, PUT, PATCH, DELETE
• Virtualmente suportado por qualquer cliente HTTP
 Hypertext Transfer Protocol HTTP 1.1 - http://tools.ietf.org/html/rfc2616
 PATCH Method for HTTP - http://tools.ietf.org/html/rfc5789
• Menor consumo de banda e overhead de processamento
• Contratos Fracos


Exemplo de uma requisição REST
GET /stocks?name=ORCL HTTP/1.1


Desafios REST


Desafios REST
• Talvez o REST como um estilo arquitetural seja MUITO
ABSTRATO
• Padronização é necessária?
• Os designers de API podem utilizar diversas abordagens
para cada tema
• Cada opção possui prós e contras, que precisam ser
ponderados durante a fase de design
• A governança pode se tornar muito complexa


Elegibilidade REST


Elegibilidade REST vs. SOAP
Aspect SOAP REST
Público Alvo Interno/Parceiros Qualquer Um

Volume de Processamento Moderado Alto, com Picos
Transação Distribuida / Orquestração WS-* / BPEL Não Padronizado

Semântica de Consistência de Dados Comumente ACID Comumente
Eventual
Contratos Fortemente Tipados Yes / WSDL / XSD WADL? / Não
Padronizado
Segurança Basic / Digest / Basic / Digest /
WS-Security OAuth / OpenID

Ferramentas Automatizadas Bastante maduras Não são maduras

Suporte de Linguagens de Programação Boa Excelente
Interoperabilidade entre implementações Bastante maduras Não são maduras

Padrões REST


Grupos dos Padrões REST
• Estratégia de
Implementação
• Segurança
• Formato de Dados
• Respostas Parciais
• Design


Estratégia de Implementação
• Construir tudo do zero
• Reutilizar o legado


Construir Tudo do Zero
• Cenário
 Infraestrutura atual inexistente ou
obsoleta
• Solução
 Criação de uma arquitetura de
referência
 Avaliar a utilização de diversos tipos de
banco de dados
 Utilização de cache distribuído
 Utilização de JMS para operações
assíncronas
• Impactos
 Necessária a avaliação de diversas
opções
 Análise de impacto de cada escolha

Reutilizar o Legado
• Cenário
 Já existem sistemas que provem todas
as informações a serem publicadas
• Solução
 Modificação da arquitetura de
referência atual para acomodar novos
requisitos
 Utilização de JMS para operações
assíncronas
• Impactos
 Risco de sobrecarga nos sistemas
legados
 Menor flexibilidade no design da
solução
 Maior latência em consultas

Segurança
• Recurso Público
• Autenticação no Recurso
• Autenticação por Terceiros
• Autorização pelo Recurso
• Autorização Centralizada
• Criptografia das Requisições/Respostas
• Criptografia do Canal


Recurso Público
• Cenário Usuário
 Não existe necessidade de Anônimo
identificação de usuários
• Solução
 Publicar o recurso tal como ele é
 Definir mecanismos de Recurso
monitoramento
• Impactos Infraestrutura Elástica
 Surtos de requisições
 Ataques de negação de serviço
 Provisionamento de Infraestrutura
Monitoramento


Autenticação no Recurso
 Restrição de acesso a um conjunto Identificado
de usuários conhecidos
• Solução
 Utilizar uma base Recurso
LDAP, SQL, chave/valor
 Criptografia de senhas usando JavaEE Container
algoritmos one-way usando salt
• Impactos JAAS
 Risco na proteção da base de
senhas
 Overhead na autenticação LDAP


Autenticação por Terceiros
 Usuários não são conhecidos Identificado
previamente pelo recurso
 Informações de identidade são de
propriedade de terceiros Resource
Facebook
• Solução Owner
 Configurar autenticação utilizando
plataforma de terceiros, tais como:
– Facebook Recurso API
– Twitter
• Impactos
 Dependência de fatores externos Base de
Usuários

Segurança
autenticação por terceiros

Referência: https://developers.facebook.com/docs/concepts/login/login-architecture/

Formato de Dados
• Versionamento de Recursos
• Multiplos formatos


Versionamento de Recursos
• Cenário
 É necessário fazer alterações /pedidos
incompatíveis no recurso
 Não é possível assegurar a migração de
todos os clientes ao mesmo tempo
• Solução V 1.0 V 2.0
 Manter por um período determinado
mais de uma versão do recurso em
operação
V 1.1
• Impactos
 Complexidade de Governança
 Aumento de custos de operação e
desenvolvimento


• Nenhum Versionamento
 Funciona como se o recurso /pedidos
estivesse sempre na versão 1
 Impede a inclusão de novos
atributos obrigatórios V 1.0
 Impede a retirada de
atributos
 Tende a deixar os recursos V 1.1
muito complexos
 Ao longo do tempo pode ser
insustentável V 1.2

Versão Única

• Versionamento na URI /pedidos
 Ex: http://api.sensedia.com/v1/pedidos
 Viola HATEOAS
 Fácil roteamento entre servidores
/v1/pedidos /v2/pedidos
 Fácil manutenção de código
 Não requer a utilização de cabeçalhos


• Versionamento na Query String
/pedidos
 Ex: http://api.sensedia.com/pedidos?_version=1
 Viola HATEOAS
 Parâmetro é opcional ou obrigatório? /pedidos? /pedidos?
 Difícil manutenção de código _version=1 _version=2
 Não requer a utilização de cabeçalhos


• Versionamento no Media Type
 Ex: http://api.sensedia.com/pedidos
– Accepts: vnd.sensedia.com.pedidos+json; version=1

 Dificulta a implementação de clientes
 Dificulta o acesso via browser (não deve ter versão
default, certo?)
 Moderada complexidade na manutenção de código


Nenhum URI Query String VND
Twitter até 2009 Twitter após 2009 Facebook Azure

Flickr Foursquare Google Data GitHub (v 3)
Dropbox Netflix *
GitHub (v 2) PayPal
Yammer EBay
Delicious
Last FM
Twillio

Múltiplos Formatos
• Cenário
 Dependendo do recurso, talvez seja /pedidos/ABCD-1234
importante representá-lo de diversas
formas.
• Solução
 Possibilitar que o cliente passe no JSON XML
header Accept, o formato desejado.
 Prover diversas alternativas de
renderização dependendo do tipo do
recurso
ICAL PDF
• Impactos
 Flexibilidade do uso pelos clientes
 Aumento de complexidade na
implementação


Respostas Parciais
• Paginação de Consultas
• Subconjunto de Atributos


Paginação de Consultas /pedidos
• Cenário
 Os resultados de pesquisas são muito Cliente Página 1
grandes, sendo desnecessário ou
inviável o acesso de uma única vez
 Necessário a redução de custos de rede
principalmente em mobile Página 2
• Solução
 Dividir o conjunto de recursos em
páginas minimizando o tamanho de Página 3
cada requisição
• Impactos
 O sistema provedor das informações
precisa suportar paginação Página 4
 Necessário a utilização de caches para
consultas

Paginação de Consultas
• Sem Paginação
 Ex: http://api.sensedia.com/v1/pedidos
 Resultados potencialmente muito grandes
 Inviável para mobile
 Pode demandar muita infraestrutura de rede
 Simples para implementar, independente da estratégia de
implementação utilizada


• Paginação na URI
– Ex 1: http://api.sensedia.com/v1/pedidos/3/50
» Página 3 com 50 registros
– Ex 2: http://api.sensedia.com/v1/pedidos/3
» Página 3
– Confunde com a URI para acesso a um elemento do conjunto:
» http://api.sensedia.com/v1/pedidos/ABCD-12345


• Paginação na Query String
– Ex: http://api.sensedia.com/v1/pedidos?_pagina=3&_tamanho=50
– Flexível pois o cliente pode ou não utilizar esse recurso
– Pode definir o tamanho da página que é mais adequado para o consumo
– Query String => Restrições
– Opção recomendada para uso geral


Paginação de Consultas: Cases Query String
• Facebook • Twitter
 Offset Based  Time Based
– Limit
– Until
– Offset
– Count
 Time Based
– Until  Cursor Based
– Since – Since_id
– Limit – Max_id
 Cursor Based
– Count
– Limit
– Before
– After

Referência: https://developers.facebook.com/docs/reference/api/pagination/
51 https://dev.twitter.com/docs/api/1.1/get/search/tweets © Copyright | www.sensedia.com

• Paginação usando HTTP Headers
– Ex: http://api.sensedia.com/v1/pedidos
– Requer uso do cabeçalho Range na requisição
» Range: pagina=3/50
– Na resposta pode ser utilizado:
» Content-Range: pagina=3/50
– Dificulta o uso no browser
– Dificulta configuração HTTP Cache
– Mantém a QueryString livre de metadados


Subconjunto de Atributos
Exemplo Filtro Positivo:
http://api.sensedia.com/v1/pedidos?_atributos=cliente,data,status,total
[{
“cliente”: {
“codigo”: “ABCD-1234”
},
“data”:"2012-10-09T01:01:01",
"status": "AGUARDANDO_PAGAMENTO",
“total”: 9.99
}]


Exemplo Filtro Positivo:
http://api.sensedia.com/v1/pedidos?_atributos=codigo,status
[{
“codigo”: “ABCD-1234”,
"status": "AGUARDANDO_PAGAMENTO”
},
{
“codigo”: “EFGH-3456”,
"status": ”ENTREGUE”
}]


Exemplo Filtro Negativo
http://api.sensedia.com/v1/pedidos/4780-DEFG?_atributos=!itens
{
“codigo”:”4780-DEFG”,
“cliente”: {
“codigo”: “ABCD-1234”
},
“data”:"2012-10-09T01:01:01",
"status": "AGUARDANDO_PAGAMENTO",
“total”: 9.99
}


Design
• Evitar refreshes desnecessários
• Referências fracas entre recursos
• Contrato Uniforme
• Processamento Assíncrono


Evitar refreshes desnecessários
• Cenário GET /v1/pedidos/ABCD-1234 HTTP/1.1
 Refreshes desnecessários podem
impactar o potencial de escalabilidade da
API Cache-Control: max-age=86400
 Recursos possuem diferences Etag: 69fafe9b
características quanto a volatilidade de {
dados
“codigo”:”ABCD-1234”,
• Solução
”status”:”AGUARDANDO_PAGAMENTO”
 Identificar essas características de
volatilidade de dados }
 Instrumentar os clientes e HTTP caches
• Impactos
 Maior esforço em tempo de design
 Maior esforço na implementação das
operações

Volatilidade de Dados
Estavel
Muito
durante a
Estavel
sessão

Estavel

Instável


Volatilidade de Dados
• Categorias • Clientes
 Alteração 1 vez ao mês  Alterações somente na
 Aceita até 1 semana de sessão
defasagem  Não há defasagem
• Produtos • Pedidos
 Alteração 1 vez por semana  Alterações frequentes
 Acetavel até 1 dia de  Não é aceitavel defasagem
defasagem


Evitar Refreshes Desnecessários
• Definir HTTP Headers (na resposta):
 Last-Modified: http://tools.ietf.org/html/rfc2616#section-13.3.1
 Cache-Control: http://tools.ietf.org/html/rfc2616#section-14.9
 ETag: http://tools.ietf.org/html/rfc2616#section-13.3.2


Referências fracas entre recursos
• Cenário
 Todos os recursos estão de certa forma
associados Clientes Pedidos
 Não é possível manipular todos os
recursos de uma só vez
• Solução
 Análise do modelo conceitual para Categorias Produtos
identificar as composições
 Agrupar as composições em um único
recurso
 Definir associação fraca entre recursos
• Impactos
 Possibilita a instrumentação de caches de
forma mais efetiva


Referências
Fortes

Referências
Fracas


Produto: Categoria:
{ {
“codigo”:”ABCD-1234”, “codigo”:”EFGH-5678”,
“descricao”:”…”, “nome”:”smartphones”
“preco”: 10.00, }
“categoria”: {
“codigo”:”EFGH-
5678”
}
}


Referências fracas entre recursos - URIs
• /categorias
• /categorias/{codigo}
• /produtos
• /produtos/{codigo}
• /clientes
• /clientes/{codigo}
• /clientes/{codigo}/enderecos
• /clientes/{codigo}/enderecos/{codigo}
• /pedidos
• /pedidos/{codigo}
• /pedidos/{codigo}/itens
• /pedidos/{codigo}/itens/{codigo}

Contrato Uniforme
• Cenário
POST /pedidos HTTP/1.1
 A manipulação dos recursos devem se
comportar de forma idêntica
• Solução
 Definir quais as operações HTTP serão aceitas 201 500
 Definir um cojunto de códigos de retorno de
sucesso e erro padronizados
 Revisar o comportamento de todos os
recursos 401 403
• Impactos
 Aumento no custo de desenvolvimento inicial
 Redução de complexidade no consumo dos
recursos

HTTP Status Codes – Casos de Sucesso
200 OK: aceito para GET
201 Created: aceito para POST, indica que o recurso foi criado com
sucesso, deverá existir o header Location: indicando a URI do novo
recurso.
202 Accepted: aceito para POST, PUT, PATCH e DELETE, indica que o
recurso criado representa um processo assíncrono, portanto, além do
header Location, deverá retornar o conteúdo com um atributo status.
Posteriormente o recurso poderá ser consultado para avaliar a alteração
do status.
204 No Content: aceito para PUT, PATCH e DELETE


HTTP Status Codes – Casos de Erro
• Exceção de negócio – retorna código 422;
• Exceção do cliente – família 400:
 400 - Requisição Mal Formada;
 401 - Requisição Requer Autenticação;
 403 - Requisição Negada;
 404 - Recurso não Encontrado;
 405 - Método não Permitido;
• Exceção do Servidor – retorna código 500;
Além do código de retorno http, os detalhes do erro devem ser
retornados no payload, com um link para a documentação do erro;


Processamento Assíncrono
• Cenário
 As operações que modificam o
estado, POST, PUT, PATCH e DELETE podem
demorar, principalmente quando dependem
do legado
• Solução
 Armazenar a requisição de forma imediata
 Retornar para o cliente com um ticket para
que ele possa consultar o status
posteriormente
 Notificação de alteração de estado
• Impactos
 Maior complexidade na implementação do
71 cliente e do recurso © Copyright | www.sensedia.com

Processamento Síncrono


Recursos com Processamento Assíncrono
• São recursos que representam (ou iniciam) a execução de processos
de longa duração.
• Na criação de um novo recurso, deverá retornar o código 202 –
Requisição Aceita
• Eventuais erros de negócio deverão ser representados na forma de
“status”, que poderão ser consultados de forma subsequente.
• Notificação de Fim de Trabalho:
 Dispositivos Móveis e Desktops: Polling
 Outros Sistemas: Notificação de Eventos


Processamento Assíncrono - Polling


Processamento Assíncrono - Callback


Ferramentas


[ Componentes
Tecnológicos ]

Partners Apps
/ Commerce REST API Traffic
API Internal Call
Business
Application 1
ESB
Platforms Gateway
Business
Application 2
Monitoring Internal Services
Control API Traffic
Policy Discovery
Deploy

Publish
Developers Web Browser Partners API
Portal Get API Usage Manager

Engage Developers Manage API documentation,
Access Keys and Usage

Q&A


Contatos

alessandro.oliveira@sensedia.com
@aro1976

felipe.firmo@sensedia.com
@felipe_firmo


Thank You!

[ Empowering Business.
Architecting IT ]


REST: Padrões e Melhores Práticas

Mais conteúdo relacionado

Mais procurados

Destaque

Semelhante a REST: Padrões e Melhores Práticas

REST: Padrões e Melhores Práticas

Notas do Editor