Contenu connexe Similaire à REST: Padrões e Melhores Práticas (20) REST: Padrões e Melhores Práticas3. 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
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
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
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
21. Grupos dos Padrões REST
• Estratégia de
Implementação
• Segurança
• Formato de Dados
• Respostas Parciais
• Design
21 © 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
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
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
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
Notes de l'éditeur Felipe, a bola ésua! – 10 minutos. 20 minutos Alessandro a bola ésua! 40 minutos F 50minutos 55 minutos