1) O documento apresenta os conceitos e práticas recomendadas para construção de APIs gerenciadas de ponta a ponta.
2) As etapas incluem planejamento da estratégia, design, construção, execução e instrumentalização da API.
3) As boas práticas abordadas incluem uso de URIs, recursos, operações, versionamento, tipos de mídia, códigos de status e instrumentação.
3. 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
Fábio Rosato
4. Agenda
Sobre a Sensedia
Contextualização
Proposta de valor e Design
Construção da API
Execução e instrumentalização
6. 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
10. O Tempo todo
com o usuário
Compartilhando
tudo com todos
The Nexus
of Forces
Inundação de dados
e contexto
Implantanto e rodando
em algum lugar
Source: Gartner (Jun/2012)
11. APIs
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
13. O tabuleiro das APIs
16
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
20. 1
Proposta
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
21. “Você pode até passar batom num porco,
mas ele continuará sendo um porco!”
22. Plan &
Prepare
API
Strategy
Muitos
projetos;
Design
Equipe
& Build
pequena
Run &
Engage
Design
Design &
&
Build
Build
23. 2
URI
Uniform Resource
Identifier
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
24. Estrutura Mínima
URI: https://api.mycompany.com/name-of-api/resource
HTTP ou
HTTPS
Seu domínio Nome da API
(opcional)
Recursos e
Parâmetros
25. 3
Recursos
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
26. REST
Representational State Transfer
Estilo arquitetural criado por Roy Fielding
RESTful
Design que respeita os conceitos REST
29. 4
Operaçõ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
32. Resumo das Operações
Resource POST
(create)
GET
(read)
PUT
(update, create)
DELETE
(delete)
/pedidos Cria novo
pedido
Lista pedidos -- Apaga todos
os pedidos
/pedidos/3747 -- Mostra pedido
3747
Atualiza pedido
3747, se não
existir, cria
Apaga pedido
3747
33. Método de Consulta
(Cachable, Safe, Idempotente)
GET /vendas/pedidos
GET /checklist/item/4
GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
34. 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
35. 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"
}
36. GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
Método para Remoção
(Unsafe, Idempotente)
DELETE /pedidos/39009186
DELETE /users/9877261/photos
37. GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
Método para Atualização parcial
(Unsafe, Não-Idempotente)
PATCH /users/9833201
{
"email": "joao.silva@empresa.com"
}
PATCH /pedidos/39009186
{
"status": "Cancelado"
}
38. GET
POST
PUT
DELETE
PATCH
OPTIONS
HEAD
OPTIONS
Quais métodos são permitidos?
OPTIONS /clientes
Allow: HEAD,GET,POST,OPTIONS
HEAD
Quero ver apenas o Header
HEAD /clientes
Date: …
Content-Type: application/json
Content-Length: 12345
39. 5
Versionamento
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
41. Versionamento
Versão
URI: https://api.mycompany.com/name-of-api/v2/resource
HTTP ou
HTTPS
Seu domínio Nome da API
(opcional)
Recursos e
Parâmetros
Outras alternativas:
• Twilio: /2010-04-01/Accounts/
• Salesforce.com: /services/data/v20.0/sobjects/Account
42. 6
Media
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
43. Media
Types
Formatos Padronizados:
application/json
application/xml
Formatos Proprietários:
vnd.{nome_empresa}.{nome_media_type}+{formato}
application/vnd.minhaempresa.pedido+json
Parâmetros no Header:
Request: Response:
Accept: application/json
Content-Type: application/json
44. 7
Status
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
45. 200
400
500
Resultado OK
Erro no Cliente
Erro no Servidor
47. Status &
Error Codes
200
400
500
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
}
]
48. Status &
Error Codes
200
400
500
201 Created
POST /items/1234/bids
{
"amount" : 602.99
}
201 Created
Location: /items/1234/bids/100001
{
"amount" : 602.99,
"current_bid" : 510,
"winning" : true
}
49. Status &
Error Codes
200
400
500
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
}
50. Status &
Error Codes
200
400
500
Outros Comuns
401
403
404
413
429
Unauthorized
Forbidden
Not Found
Request is too Large
Too Many Requests
51. Status &
Error Codes
200
400
500
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
52. 8
Filtros 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
53. Filtros
Busca Global:
GET /search?q=macbook+air
Busca com escopo (subconjuntos):
GET /vendas/v2/pedidos?status=concluido
Respostas parciais:
GET /pedidos/123AF15J?_fields=numero,data,valor
54. Paginação
Recomendação:
GET /pedidos?_offset=50&_limit=25
Outras opções:
Linkedin:
Instagram:
?start=50&count=25
?min_id=3091&max_id=3245&count=25
55. 9
Caching
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
56. Caching
Evite tráfego desnecessário
Latência de rede
Sobrecarga nos servidores
Atenção
Tempo de invalidação do cache
Sincronização em clusters
57. 10
Seguranç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
58. Acesso não autorizado
Ataques
Sobrecarga
Confidencialidade
Implementações
desastradas em clients
59. Acesso não autorizado
Ataques
Sobrecarga
Confidencialidade
Implementações
desastradas em clients
62. 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
Mobile Apps Partners’ Apps
Internal Services
@Backend
API Gateway Architecture
63. 11
Callbacks
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
64. Já chegamos?
Já chegamos?
Já chegamos?
Já chegamos?
Já chegamos?
Stop Pooling Me
65. Marketplace API
Chamadas Reversas:
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
66. 12
Hypermedia
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
67. Hypermedia APIs
HATEOAS = Hypermedia as the
Engine of Application State
*POX = Plain Old XML, Richardson Maturity Model
68. GET /items?q=macbook+air+new
{
"results" : [
{
"id" : 123,
"name" : "Macbook Air 2010 LIKE NEW",
"price" : "499"
}
]
}
SEM
Hypermedia
69. COM
Hypermedia
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"
}
]
}
70. Plan &
Prepare
API
Strategy
Design
& Build
Muitos
projetos;
Run Run Run &
&
&
Engage
Equipe
Engage
Engage
pequena
71. 13
Documentaçã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
73. Developers
https://developers.[you].com
API Portal
API Developers Portal
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
Powered by
79. REST Console ou
Sandbox / Playgroung
dev.transparencia.org.br
80. 14
Construçã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
82. 15
Instrumentalizaçã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
83.
84. Problemas de
Performance
Indisponibilidade
Bugs Confiabilidade
Mudanças
(não-planejadas)
Falta de
Suporte
85. 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
89. 16
Divulgaçã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
93. 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