1.
[ Empowering Business.
Architecting IT ]
1 © Copyright | www.sensedia.com

2.
REST: Patterns & Best Practices
2 © Copyright | www.sensedia.com

3.
Quem somos nós
alessandro.oliveira@sensedia.com
@aro1976
felipe.firmo@sensedia.com
@felipe_firmo
3 © Copyright | www.sensedia.com

4.
Público Alvo
API Designer
Diretor Arquiteto
Gerente Programador
4 © Copyright | www.sensedia.com

5.
Agenda
• Sobre a Sensedia
• SOAP vs. REST
• Elegibilidade de REST
• Desafios de REST
• Padrões e Melhores Práticas REST
• Ferramentas
• Q&A
5 © Copyright | www.sensedia.com

6.
[ 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
6 © Copyright | www.sensedia.com

7.
[ Sobre a
Sensedia ]
Profundo conhecimento em:
√ SOA (Service Oriented Architechture)
√ Governança
√ Enterprise Architecture
√ Cloud Computing
7 © Copyright | www.sensedia.com

8.
[ 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.
8 © Copyright | www.sensedia.com

9.
[ 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
9 © Copyright | www.sensedia.com

10.
[ Quem tem experimentado
a proposta de valor da Sensedia ]
10 © Copyright | www.sensedia.com

11.
SOAP vs. REST
11 © Copyright | www.sensedia.com

12.
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
12 © Copyright | www.sensedia.com

13.
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>
13 © Copyright | www.sensedia.com

14.
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
14 © Copyright | www.sensedia.com

15.
Exemplo de uma requisição REST
GET /stocks?name=ORCL HTTP/1.1
15 © Copyright | www.sensedia.com

16.
Desafios REST
16 © Copyright | www.sensedia.com

17.
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
17 © Copyright | www.sensedia.com

18.
Elegibilidade REST
18 © Copyright | www.sensedia.com

19.
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
19 © Copyright | www.sensedia.com
Interoperabilidade entre implementações Bastante maduras Não são maduras

20.
Padrões REST
20 © Copyright | www.sensedia.com

21.
Grupos dos Padrões REST
• Estratégia de
Implementação
• Segurança
• Formato de Dados
• Respostas Parciais
• Design
21 © Copyright | www.sensedia.com

22.
Estratégia de Implementação
• Construir tudo do zero
• Reutilizar o legado
22 © Copyright | www.sensedia.com

23.
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
23 © Copyright | www.sensedia.com

24.
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
25 © Copyright | www.sensedia.com

25.
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
27 © Copyright | www.sensedia.com

26.
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
28 © Copyright | www.sensedia.com

27.
Autenticação no Recurso
• Cenário Usuário
 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
30 © Copyright | www.sensedia.com

28.
Autenticação por Terceiros
• Cenário Usuário
 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
32 © Copyright | www.sensedia.com

29.
Segurança
autenticação por terceiros
Referência: https://developers.facebook.com/docs/concepts/login/login-architecture/
34 © Copyright | www.sensedia.com

30.
Formato de Dados
• Versionamento de Recursos
• Multiplos formatos
35 © Copyright | www.sensedia.com

31.
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
36 © Copyright | www.sensedia.com

32.
Versionamento de Recursos
• 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
38 © Copyright | www.sensedia.com

33.
Versionamento de Recursos
• 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
39 © Copyright | www.sensedia.com

34.
Versionamento de Recursos
• 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
40 © Copyright | www.sensedia.com

35.
Versionamento de Recursos
• 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
41 © Copyright | www.sensedia.com

36.
Versionamento de Recursos
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
42 © Copyright | www.sensedia.com

37.
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
43 © Copyright | www.sensedia.com

38.
Respostas Parciais
• Paginação de Consultas
• Subconjunto de Atributos
45 © Copyright | www.sensedia.com

39.
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
46 © Copyright | www.sensedia.com

40.
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
48 © Copyright | www.sensedia.com

41.
Paginação de Consultas
• 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
49 © Copyright | www.sensedia.com

42.
Paginação de Consultas
• 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
50 © Copyright | www.sensedia.com

43.
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

44.
Paginação de Consultas
• 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
52 © Copyright | www.sensedia.com

45.
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
}]
54 © Copyright | www.sensedia.com

46.
Subconjunto de Atributos
Exemplo Filtro Positivo:
http://api.sensedia.com/v1/pedidos?_atributos=codigo,status
[{
“codigo”: “ABCD-1234”,
"status": "AGUARDANDO_PAGAMENTO”
},
{
“codigo”: “EFGH-3456”,
"status": ”ENTREGUE”
}]
55 © Copyright | www.sensedia.com

47.
Subconjunto de Atributos
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
}
56 © Copyright | www.sensedia.com

48.
Design
• Evitar refreshes desnecessários
• Referências fracas entre recursos
• Contrato Uniforme
• Processamento Assíncrono
57 © Copyright | www.sensedia.com

49.
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
59 © Copyright | www.sensedia.com

50.
Volatilidade de Dados
Estavel
Muito
durante a
Estavel
sessão
Estavel
Instável
60 © Copyright | www.sensedia.com

51.
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
61 © Copyright | www.sensedia.com

52.
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
62 © Copyright | www.sensedia.com

53.
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
63 © Copyright | www.sensedia.com

54.
Referências fracas entre recursos
Referências
Fortes
Referências
Fracas
65 © Copyright | www.sensedia.com

55.
Referências fracas entre recursos
Produto: Categoria:
{ {
“codigo”:”ABCD-1234”, “codigo”:”EFGH-5678”,
“descricao”:”…”, “nome”:”smartphones”
“preco”: 10.00, }
“categoria”: {
“codigo”:”EFGH-
5678”
}
}
66 © Copyright | www.sensedia.com

56.
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}
67 © Copyright | www.sensedia.com

57.
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
68 © Copyright | www.sensedia.com

58.
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
69 © Copyright | www.sensedia.com

59.
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;
70 © Copyright | www.sensedia.com

60.
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

61.
Processamento Síncrono
72 © Copyright | www.sensedia.com

62.
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
73 © Copyright | www.sensedia.com

63.
Processamento Assíncrono - Polling
74 © Copyright | www.sensedia.com

64.
Processamento Assíncrono - Callback
75 © Copyright | www.sensedia.com

65.
Ferramentas
76 © Copyright | www.sensedia.com

66.
[ 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

67.
Q&A
78 © Copyright | www.sensedia.com

68.
Contatos
alessandro.oliveira@sensedia.com
@aro1976
felipe.firmo@sensedia.com
@felipe_firmo
79 © Copyright | www.sensedia.com

69.
Thank You!
[ Empowering Business.
Architecting IT ]
80 © Copyright | www.sensedia.com