rest - padroes e melhores praticas

[ Empowering Business. Architecting IT ]

REST: Padrões & Melhores Práticas

Quem somos nós

alessandro.oliveira@sensedia.com

@aro1976

felipe.firmo@sensedia.com

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

Exemplo de uma requisição REST

GET /stocks?name=ORCL HTTP/1.1

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

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

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

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

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

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 ]

Contatos

alessandro.oliveira@sensedia.com

@aro1976

felipe.firmo@sensedia.com

@felipe_firmo

[ Empowering Business. Architecting IT ]

Thank You!

rest - padroes e melhores praticas

Technology

coedi padroes educ infantil

padroes de projetos gof

padroes de intenção

tdc2015: testes em apis rest com rest-assured

palestra sobre automação de testes em apis rest com...

tcc - rest

padroes command 131010061632 phpapp02

padroes livres

3 padroes-web-intro-javascript

rest x soap

padroes de projeto - introducao

web services rest

padroes hipnóticos da linguagem

web services rest (java)

uso de padroes de analise e padroes de projeto

padroes de desenho

apis rest com apigility

padroes respiratorios

manual padroes visuais samu

rest apis com django