Upload
felipe-firmo
View
3.416
Download
4
Embed Size (px)
DESCRIPTION
Apresentação realizada em 05/12/2012 no JavaOneBrasil, com o Alessandro Oliveira pela Sensedia. O objetivo dessa palestra foi apresentar o trabalho em andamento sobre o tema REST para a publicação de APIs por clientes de grande porte.
Citation preview
© Copyright | www.sensedia.com 1
[ Empowering Business. Architecting IT ]
© Copyright | www.sensedia.com 2
REST: Padrões & Melhores Práticas
© Copyright | www.sensedia.com 3
Quem somos nós
@aro1976
@felipe_firmo
© Copyright | www.sensedia.com 4
Público Alvo
API Designer
Arquiteto
ProgramadorGerente
Diretor
© 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
© 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
© Copyright | www.sensedia.com 7
[ Sobre a Sensedia ]
Profundo conhecimento em:
√ SOA (Service Oriented Architechture)
√ Governança
√ Enterprise Architecture
√ Cloud Computing
© Copyright | www.sensedia.com 8
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 ]
© Copyright | www.sensedia.com 9
Philadelphia, EUA São Paulo, BR Campinas, BR
Sede em Campinas, SP e escritórios em São Paulo, SP e Philadelphia, EUA
[ Sobre a Sensedia ]
© Copyright | www.sensedia.com 10
[ Quem tem experimentado a proposta de valor da Sensedia ]
© Copyright | www.sensedia.com 11
SOAP vs. REST
© 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
© 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>
© 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
© Copyright | www.sensedia.com 15
Exemplo de uma requisição REST
GET /stocks?name=ORCL HTTP/1.1
© Copyright | www.sensedia.com 16
Desafios REST
© 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
© Copyright | www.sensedia.com 18
Elegibilidade REST
© 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 /
WS-Security
Basic / Digest /
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
© Copyright | www.sensedia.com 20
Padrões REST
© Copyright | www.sensedia.com 21
Grupos dos Padrões REST
• Estratégia de
Implementação
• Segurança
• Formato de Dados
• Respostas Parciais
• Design
© Copyright | www.sensedia.com 22
• Construir tudo do zero
• Reutilizar o legado
Estratégia de Implementação
© 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
© 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
© Copyright | www.sensedia.com 25
• 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
Segurança
© Copyright | www.sensedia.com 26
JavaEE Container
Autenticação no Recurso • Cenário
Restrição de acesso a um conjunto de usuários conhecidos
• Solução
Utilizar uma base LDAP, SQL, chave/valor
Criptografia de senhas usando algoritmos one-way usando salt
• Impactos
Risco na proteção da base de senhas
Overhead na autenticação
Usuário
Identificado
Recurso
LDAP
JAAS
© Copyright | www.sensedia.com 27
Autenticação por Terceiros • Cenário
Usuários não são conhecidos previamente pelo recurso
Informações de identidade são de propriedade de terceiros
• Solução
Configurar autenticação utilizando plataforma de terceiros, tais como:
• Impactos
Dependência de fatores externos
Usuário
Identificado
Resource
Owner Facebook
Base de
Usuários
Recurso API
© Copyright | www.sensedia.com 28
Segurança autenticação por terceiros
Referência: https://developers.facebook.com/docs/concepts/login/login-architecture/
© Copyright | www.sensedia.com 29
• Versionamento de Recursos
• Multiplos formatos
Formato de Dados
© Copyright | www.sensedia.com 30
Versionamento de Recursos • Cenário
É necessário fazer alterações incompatíveis no recurso
Não é possível assegurar a migração de todos os clientes ao mesmo tempo
• Solução
Manter por um período determinado mais de uma versão do recurso em operação
• Impactos
Complexidade de Governança
Aumento de custos de operação e desenvolvimento
/pedidos
V 1.0 V 2.0
V 1.1
© Copyright | www.sensedia.com 31
Versão Única
Versionamento de Recursos • Nenhum Versionamento
Funciona como se o recurso estivesse sempre na versão 1
Impede a inclusão de novos atributos obrigatórios
Impede a retirada de atributos
Tende a deixar os recursos muito complexos
Ao longo do tempo pode ser insustentável
/pedidos
V 1.0
V 1.1
V 1.2
© Copyright | www.sensedia.com 32
Versionamento de Recursos
• Versionamento na URI Ex: http://api.sensedia.com/v1/pedidos
Viola HATEOAS
Fácil roteamento entre servidores
Fácil manutenção de código
Não requer a utilização de cabeçalhos
/pedidos
/v1/pedidos /v2/pedidos
© Copyright | www.sensedia.com 33
Versionamento de Recursos • Versionamento na Query String
Ex: http://api.sensedia.com/pedidos?_version=1
Viola HATEOAS
Parâmetro é opcional ou obrigatório?
Difícil manutenção de código
Não requer a utilização de cabeçalhos
/pedidos
/pedidos?
_version=1
/pedidos?
_version=2
© Copyright | www.sensedia.com 34
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
© Copyright | www.sensedia.com 35
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
© Copyright | www.sensedia.com 36
Múltiplos Formatos • Cenário
Dependendo do recurso, talvez seja importante representá-lo de diversas formas.
• Solução
Possibilitar que o cliente passe no header Accept, o formato desejado.
Prover diversas alternativas de renderização dependendo do tipo do recurso
• Impactos
Flexibilidade do uso pelos clientes
Aumento de complexidade na implementação
/pedidos/ABCD-1234
JSON XML
ICAL PDF
© Copyright | www.sensedia.com 37
• Paginação de Consultas
• Subconjunto de Atributos
Respostas Parciais
© Copyright | www.sensedia.com 38
/pedidos Paginação de Consultas
• Cenário
Os resultados de pesquisas são muito 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
• Solução
Dividir o conjunto de recursos em páginas minimizando o tamanho de cada requisição
• Impactos
O sistema provedor das informações precisa suportar paginação
Necessário a utilização de caches para consultas
Cliente
Página 2
Página 1
Página 3
Página 4
© Copyright | www.sensedia.com 39
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
© Copyright | www.sensedia.com 40
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
© Copyright | www.sensedia.com 41
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
© Copyright | www.sensedia.com 42
Paginação de Consultas: Cases Query String
• Facebook Offset Based
– Limit – Offset
Time Based – Until – Since – Limit
Cursor Based – Limit – Before – After
• Twitter Time Based
– Until
– Count
Cursor Based
– Since_id
– Max_id
– Count
Referência: https://developers.facebook.com/docs/reference/api/pagination/ https://dev.twitter.com/docs/api/1.1/get/search/tweets
© Copyright | www.sensedia.com 43
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
© Copyright | www.sensedia.com 44
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
}]
© Copyright | www.sensedia.com 45
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”
}]
© Copyright | www.sensedia.com 46
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
}
© Copyright | www.sensedia.com 47
• Evitar refreshes desnecessários
• Referências fracas entre recursos
• Contrato Uniforme
• Processamento Assíncrono
Design
© Copyright | www.sensedia.com 48
Evitar refreshes desnecessários • Cenário
Refreshes desnecessários podem impactar o potencial de escalabilidade da API
Recursos possuem diferences características quanto a volatilidade de dados
• Solução
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
GET /v1/pedidos/ABCD-1234 HTTP/1.1
Cache-Control: max-age=86400
Etag: 69fafe9b
{
“codigo”:”ABCD-1234”,
”status”:”AGUARDANDO_PAGAMENTO”
}
© Copyright | www.sensedia.com 49
Volatilidade de Dados
Muito
Estavel
Estavel
Estavel
durante a
sessão
Instável
© Copyright | www.sensedia.com 50
Volatilidade de Dados • Categorias
Alteração 1 vez ao mês
Aceita até 1 semana de defasagem
• Produtos
Alteração 1 vez por semana
Acetavel até 1 dia de defasagem
• Clientes
Alterações somente na sessão
Não há defasagem
• Pedidos
Alterações frequentes
Não é aceitavel defasagem
© Copyright | www.sensedia.com 51
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
© Copyright | www.sensedia.com 52
Referências fracas entre recursos • Cenário
Todos os recursos estão de certa forma associados
Não é possível manipular todos os recursos de uma só vez
• Solução
Análise do modelo conceitual para 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
Clientes Pedidos
Produtos Categorias
© Copyright | www.sensedia.com 53
Referências fracas entre recursos
Referências
Fortes
Referências
Fracas
© Copyright | www.sensedia.com 54
Referências fracas entre recursos Produto: { “codigo”:”ABCD-1234”, “descricao”:”…”, “preco”: 10.00, “categoria”: { “codigo”:”EFGH-5678” } }
Categoria: { “codigo”:”EFGH-5678”, “nome”:”smartphones” }
© Copyright | www.sensedia.com 55
• /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}
Referências fracas entre recursos - URIs
© Copyright | www.sensedia.com 56
Contrato Uniforme • Cenário
A manipulação dos recursos devem se comportar de forma idêntica
• Solução
Definir quais as operações HTTP serão aceitas
Definir um cojunto de códigos de retorno de sucesso e erro padronizados
Revisar o comportamento de todos os recursos
• Impactos
Aumento no custo de desenvolvimento inicial
Redução de complexidade no consumo dos recursos
POST /pedidos HTTP/1.1
201 500
401 403
© Copyright | www.sensedia.com 57
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 Sucesso
© Copyright | www.sensedia.com 58
• 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;
HTTP Status Codes – Casos de Erro
© Copyright | www.sensedia.com 59
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 cliente e do recurso
© Copyright | www.sensedia.com 60
Processamento Síncrono
© Copyright | www.sensedia.com 61
• 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
Recursos com Processamento Assíncrono
© Copyright | www.sensedia.com 62
Processamento Assíncrono - Polling
© Copyright | www.sensedia.com 63
Processamento Assíncrono - Callback
© Copyright | www.sensedia.com 64
Ferramentas
API Manager
Partners Portal
API Gateway ESB
Business
Application 1
Business
Application 2
Engage Developers Manage API documentation, Access Keys and Usage
Control API Traffic
Developers
REST API Traffic
Publish
Monitoring
Policy Deploy
Web Browser
Internal Call
Get API Usage
Internal Services Discovery
Partners Apps / Commerce
Platforms
[ Componentes Tecnológicos ]
© Copyright | www.sensedia.com 66
Q & A
© Copyright | www.sensedia.com 67
Contatos
@aro1976
@felipe_firmo
© Copyright | www.sensedia.com 68
[ Empowering Business. Architecting IT ]
Thank You!