José Vahl
Fábio Rosato
Gerente de Consultoria na Sensedia
Professor dos cursos de pós-graduação em SOA pelo IBMEC e Inatel
Atuação em diversos projetos complexos para grandes empresas grandes Cielo, Telefônica | Vivo, TIM,
Itaú, Bradesco Seguros entre outras
Agenda
Sobre a Sensedia
Contextualização
Proposta de valor e Design
Construção da API
Execução e instrumentalização
Sobre a Sensedia
Design, Exposição, Gerenciamento e Engajamento em APIs
Headquarter em Campinas, escritórios em São Paulo, Rio e Philadelphia
Classificados como Visionários no Quadrante Mágico do Gartner
(*) Magic Quadrant for Integrated SOA Governance Technology Sets, 2009
Contextualização
The Internetof Things
O Tempo todocom o usuário
Compartilhandotudo com todos
Inundação de dados e contexto
Implantanto e rodandoem algum lugar
Source: Gartner (Jun/2012)
The Nexus of Forces
Application Programming Interface é a cola digital que permite:
• Acelerar parcerias• Simplificar integração mobile-cloud• Impulsionar a inovação aberta• Integrar aplicações de software• e Criar novos negócios
APIs
Proposta de valor e design
16O tabuleiro das APIs
casas
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
APIStrategy
Plan &Prepare
Design& Build
Run &Engage
APIStrategy
Plan &Prepare
Design& Build
Run &Engage
Plan &Prepare
As primeiras decisões de design…
Selecione a Tecnologia Adequada
RESTSOAP vs.
Selecione a Tecnologia Adequada
JSONXML vs.
and the winners are…
REST + JSON
1Proposta de valor
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
“Você pode até passar batom num porco,mas ele continuará sendo um porco!”
APIStrategy
Plan &Prepare
Design& Build
Run &Engage
Design &
Build
Muitosprojetos;Equipe
pequena
Design &Build
2URI
Uniform ResourceIdentifier
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
URI: https://api.mycompany.com/name-of-api/resource
Estrutura Mínima
HTTP ouHTTPS
Seu domínio Nome da API(opcional)
Recursos eParâmetros
3Recursos
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
RESTRepresentational State TransferEstilo arquitetural criado por Roy Fielding
RESTfulDesign que respeita os conceitos REST
Coleção
/pedidos
Resources
Elemento
/pedidos/{id}
/getAccount
/getAllAccounts
/createDirectory
/updateGroupName
/findClientById
RPC?
4Operações
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
GET POST PUT DELETE
Resumo das Operações
Resource POST(create)
GET(read)
PUT(update, create)
DELETE(delete)
/pedidos Cria novo pedido
Lista pedidos -- Apaga todosos pedidos
/pedidos/3747 -- Mostra pedido3747
Atualiza pedido3747, se nãoexistir, cria
Apaga pedido3747
Método de Consulta(Cachable, Safe, Idempotente)
GET /vendas/pedidos
GET /checklist/item/4
GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
Método para “Criação”(Unsafe, Não-Idempotente)
POST /clientes/9833201/enderecos
{
"endereco": "Av. Brigadeiro Faria Lima",
"numero": "3800",
"complemento": "18o. Andar",
"bairro": "Itaim Bibi",
"cidade": "São Paulo",
"estado": "SP",
"cep": "04538-132"
}
GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
Método para “Atualização”(Unsafe, Idempotente)
PUT /clientes/9833201/enderecos/1
{
"endereco": "Av. Brigadeiro Faria Lima",
"numero": "3800",
"complemento": "18o. Andar",
"bairro": "Itaim Bibi",
"cidade": "São Paulo",
"estado": "SP",
"cep": "04538-132"
}
GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
Método para Remoção(Unsafe, Idempotente)
DELETE /pedidos/39009186
DELETE /users/9877261/photos
GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
Método para Atualização parcial(Unsafe, Não-Idempotente)
PATCH /users/9833201
{
"email": "[email protected]"
}
PATCH /pedidos/39009186
{
"status": "Cancelado"
}
GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
OPTIONSQuais métodos são permitidos?
OPTIONS /clientes
Allow: HEAD,GET,POST,OPTIONS
HEADQuero ver apenas o Header
HEAD /clientes
Date: …
Content-Type: application/json
Content-Length: 12345
5Versionamento
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
v1 v2 v3 v4 v5 v6 v7
THINGS CHANGE!
Versionamento
Versão
URI: https://api.mycompany.com/name-of-api/v2/resource
HTTP ouHTTPS
Seu domínio Nome da API(opcional)
Recursos eParâmetros
Outras alternativas:• Twilio: /2010-04-01/Accounts/ • Salesforce.com: /services/data/v20.0/sobjects/Account
6Media Types
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Media Types
application/json
vnd.{nome_empresa}.{nome_media_type}+{formato}
application/xml
Formatos Padronizados:
Formatos Proprietários:
application/vnd.minhaempresa.pedido+json
Accept: application/json
Parâmetros no Header:
Content-Type: application/json
Response:Request:
7Status Codes
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
200
400
500
Resultado OK
Erro no Cliente
Erro no Servidor
STATUS OK 200
200
400
500
Status & Error Codes
200 OK
GET /candidatos?estado=SP&partido=PP
200 OK
[
{
"id": "1532962",
"apelido": "PAULO MALUF",
"nome": "PAULO SALIM MALUF",
"numero": "1111",
"cargo": "Deputado Federal",
"estado": "SP",
"partido": "PP",
"reeleicao": true
}
]
200
400
500
Status & Error Codes
201 Created
POST /items/1234/bids
{
"amount" : 602.99
}
201 Created
Location: /items/1234/bids/100001
{
"amount" : 602.99,
"current_bid" : 510,
"winning" : true
}
200
400
500
Status & Error Codes
400 Bad Request
GET /candidatos
400 Bad Request
{
"status" : 400,
"code" : 40377,
"message" : "Parâmetro 'estado' não
pode ser nulo ou vazio"
"more" : https://dev.empresa.com/errors/40377
}
200
400
500
Status & Error Codes
Outros Comuns
401
403
404
413
429
Unauthorized
Forbidden
Not Found
Request is too Large
Too Many Requests
200
400
500
Status & Error Codes
500 Internal Server Error
PUT /vendas/v1/pedidos/9940382
{
”status" : canceled
}
500 Internal Server Error
{
"status" : 500,
"message": ”Oops. Algo saiu errado”
}
http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
8Filtros e
Paginação
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
FiltrosGET /vendas/v2/pedidos?status=concluido
GET /pedidos/123AF15J?_fields=numero,data,valor
Busca com escopo (subconjuntos):
Respostas parciais:
GET /search?q=macbook+air
Busca Global:
Paginação
GET /pedidos?_offset=50&_limit=25
Recomendação:
Outras opções:
Linkedin:
Instagram:
?start=50&count=25
?min_id=3091&max_id=3245&count=25
9Caching
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Caching
Evite tráfego desnecessárioLatência de rede
Sobrecarga nos servidores
Atenção
Tempo de invalidação do cache Sincronização em clusters
10Segurança
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Acesso não autorizado
Ataques
Sobrecarga
Confidencialidade
Implementações desastradas em clients
Acesso não autorizado
Ataques
Sobrecarga
Confidencialidade
Implementações desastradas em clients
Identificar App (?)
Identificar Usuário (?)
Identificar Device (?)
Identidade e
Autorização
Realtime API Traffic
https://api.[you].com/…
Powered by
API Gateway
Rate Limiting
Monitoring & Alerts
Authentication Models
Policy Enforcement
Exception handling
Analytics on API Consumption
Partners’ AppsMobile Apps
Internal Services@Backend
API Gateway Architecture
11Callbacks
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Já chegamos?Já chegamos?
Já chegamos?Já chegamos?
Já chegamos?
Stop Pooling Me
Marketplace API
Consulta estoque
Cálculo de frete
Novo pedido recebido
https://api.mywebstore.com/v1/estoque
https://api.mywebstore.com/v1/frete
https://api.mywebstore.com/v1/pedido
Chamadas Reversas:
12Hypermedia
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Hypermedia APIs
*POX = Plain Old XML, Richardson Maturity Model
HATEOAS = Hypermedia as the Engine of Application State
GET /items?q=macbook+air+new
{
"results" : [
{
"id" : 123,
"name" : "Macbook Air 2010 LIKE NEW",
"price" : "499"
}
]
}
SEMHypermedia
COMHypermedia
GET /items?q=macbook+air+new
{
"results" : [
{
"_links" : [
{"rel": "self","uri": "/items/123" },
{"rel": "bids","uri": "/items/123/bids" },
{"rel": "win","uri": "/items/123/bids?q=win" }
],
"name" : "Macbook Air 2010 LIKE NEW",
"price" : "499"
}
]
}
APIStrategy
Plan &Prepare
Design& Build
Run &Engage
Run &Engage
Muitosprojetos;Equipe
pequena
Run &Engage
13Documentação
interativa
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Docs incompletos, desatualizados, estáticos e com PDFs de 100 páginas
API Portal
Developers
https://developers.[you].com
Powered by
Introdução, tutoriais e exemplos de códigos
Self-service Signup
Documentação interativa(API Browsing)
Forum, Blog & Dev support
Testes facilitados (Sandbox)
Dev. Dashboard
API Developers Portal
Getting Started
www.twilio.com/docs
DocumentaçãoInterativa
desenvolvedores.extra.com.br
Exemplos de código nalinguagem
do developer
sendgrid.com/docs
Sign-up e Tokens de acesso automáticos
stripe.com/docs
REST Console ouSandbox / Playgroung
dev.transparencia.org.br
14Construção
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Hold on…
15Instrumentalização
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
ConfiabilidadeBugs
Problemas de Performance
Indisponibilidade
Mudanças(não-planejadas)
Falta de Suporte
API Suite
• Login / signup
• Criação de Apps
• Gestão de tokens
• Foruns e suporte
• Sandbox
• Dev Dashboard
Backend
• Autenticação
• Roteamento
• Políticas / quotas
• Degub / trace
• Monitoramento
• Gestão de tokens
www.sensedia.com/br
Trace de calls,Monitoramento,Rate Limiting e
Alertas
status.aws.amazon.com
Status Page, Release Notes,
Blog
Foruns de discussãoe Abertura de tickets
desenvolvedores.extra.com.br
16Divulgação
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Hackathon & Open Innovation
1 Apps criadas: 300+
2 Developers cadastrados: 800+
3 Tráfego: 20M calls / 15 dias
4 Eleições mais transparentes!
APIStrategy
Plan &Prepare
Design& Build
Run &Engage
Valor URI Recursos Operações
Versionamento Media Types Status Codes Filtros
Caching Segurança Callbacks Hypermedia
Documentação Construção Instrum/zação Divulgação
Construção da API
Execução e instrumentalização
Junte-se ao time!
Fábio [email protected]@frosato
José [email protected]@josevahl