REST - Padroes e Melhores Praticas

© Copyright | www.sensedia.com 1

[ Empowering Business. Architecting IT ]


REST: Padrões & Melhores Práticas


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



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.



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

Sede em Campinas, SP e escritórios em São Paulo, SP e 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

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







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 /

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


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

Resource

Owner Facebook

Base de

Usuários

Recurso API


Segurança autenticaçã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


/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


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

}]


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”

}]


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

}


• 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=86400

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

Produtos Categorias


Referências fracas entre recursos

Referências

Fortes

Referências

Fracas


Referências fracas entre recursos Produto: { “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

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 ]


Q & A


Contatos

[email protected]

@aro1976

[email protected]

@felipe_firmo


[ Empowering Business. Architecting IT ]

Thank You!

Technology

REST - Padroes e Melhores Praticas