rest: padrões e melhores práticas

© Copyright | www.sensedia.com1

[ Empowering Business.Architecting IT ]


REST: Patterns & Best Practices


Quem somos nós

[email protected]@aro1976

[email protected]@felipe_firmo


Público Alvo

API Designer

Arquiteto

ProgramadorGerente

Diretor


Agenda

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


[ Sobre aSensedia ]

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

Ajudamos empresas a seremMais Ágeis, Flexíveis e Inovadoras

Crescimento consistente:63% CAGR 2007-2011


[ Sobre aSensedia ]

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


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 aSensedia ]


Philadelphia, EUASão Paulo, BRCampinas, BR

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

[ Sobre aSensedia ]


[ Quem tem experimentadoa 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 SOAPPOST /Stock HTTP/1.1Host: www.stockexchange.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: 299SOAPAction: "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

http://tools.ietf.org/html/rfc2616







Exemplo de uma requisição RESTGET /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. SOAPAspect 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


Padrões REST


Grupos dos Padrões REST• Estratégia de

Implementação

• Segurança

• Formato de Dados

• Respostas Parciais

• Design


• Construir tudo do zero• Reutilizar o legado

Estratégia de Implementação


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


• 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


Infraestrutura Elástica

Recurso Público• Cenário

Não existe necessidade de identificação de usuários

• Solução Publicar o recurso tal como ele é Definir mecanismos de

monitoramento• Impactos

Surtos de requisições Ataques de negação de serviço Provisionamento de Infraestrutura

Usuário Anônimo

Recurso

Monitoramento


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


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:– Facebook– Twitter

• Impactos Dependência de fatores externos

Usuário Identificado

ResourceOwner

Facebook

Base de Usuários

Recurso API


Segurançaautenticação por terceiros

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


• Versionamento de Recursos• Multiplos formatos

Formato de Dados


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


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


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


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


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


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


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


• Paginação de Consultas• Subconjunto de Atributos

Respostas Parciais


/pedidosPaginaçã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


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


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


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


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


Subconjunto de AtributosExemplo 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

}]


Subconjunto de AtributosExemplo Filtro Positivo: http://api.sensedia.com/v1/pedidos?_atributos=codigo,status[{

“codigo”: “ABCD-1234”,"status": "AGUARDANDO_PAGAMENTO”

},{

“codigo”: “EFGH-3456”,"status": ”ENTREGUE”

}]


Subconjunto de AtributosExemplo Filtro Negativohttp://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

}


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

Design


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=86400Etag: 69fafe9b{ “codigo”:”ABCD-1234”, ”status”:”AGUARDANDO_PAGAMENTO”}


Volatilidade de Dados

Muito Estavel

Estavel

Estavel durante a sessão

Instável


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


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

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

ProdutosCategorias


Referências fracas entre recursos

ReferênciasFortes

ReferênciasFracas


Referências fracas entre recursosProduto:{

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

}

Categoria:{

“codigo”:”EFGH-5678”,“nome”:”smartphones”

}


• /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


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


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


• 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


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


Processamento Sí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

Recursos com Processamento Assíncrono


Processamento Assíncrono - Polling


Processamento Assíncrono - Callback


Ferramentas

APIManager

PartnersPortal

APIGateway ESB

Business Application 1

Business Application 2

Engage Developers Manage API documentation,Access Keys and Usage

Control API Traffic

Developers

REST API Traffic

Publish

MonitoringPolicyDeploy

Web Browser

Internal Call

Get API Usage

Internal ServicesDiscovery

Partners Apps/ Commerce

Platforms

[ Componentes Tecnológicos ]


Q & A


Contatos

[email protected]@aro1976

[email protected]@felipe_firmo


[ Empowering Business.Architecting IT ]

Thank You!

rest: padrões e melhores práticas

Technology

rest rest

canal27 copyright

eua9 copyright

rest11 copyright

rest soap

cada escolha23 copyright

padres rest20 copyright

desafios rest16 copyright