Este documento apresenta 10 atributos de uma API de sucesso. São eles: 1) Proposta de valor, 2) Design RESTful, 3) Versionamento, 4) Tratamento de erros, 5) Segurança, 6) Hypermedia, 7) Portal para desenvolvedores, 8) Autoatendimento e 9) Confiabilidade. O documento discute cada um destes atributos e fornece exemplos para ilustrar boas práticas de design e implementação de APIs.

1. Kleber
Bacili
kleber.bacili@sensedia.com
@kleberbacili
10
atributos
de
uma
API
de
sucesso

2. www.slideshare.net/kleberbacili/

3. Kleber
Bacili
kleber.bacili@sensedia.com
@kleberbacili
Cerquilho

4. v Design,
Exposição,
Gerenciamento
e
Engajamento
em
APIs
v Headquarter
em
Campinas,
escritórios
em
Sampa,
Rio
e
Philly
v Classificados
como
Visionários
no
Quadrante
Mágico
do
Gartner
(*)
Magic
Quadrant
for
Integrated
SOA
Governance
Technology
Sets,
2009

5. Agenda
Contextualização
Planejamento
e
Preparação
Design
e
Construção
Execução
e
Engajamento

6. Contextualização

7. O
Tempo
todo
com
o
usuário
ComparKlhando
tudo
com
todos
Inundação
de
dados
e
contexto
Implantanto
e
rodando
em
algum
lugar
Source:
Gartner
(Jun/2012)
The
Nexus
of
Forces

8. The
Internet
of
Things

10. 10Atributos
de
uma
API
de
sucesso

11. API
Strategy
Plan
&
Prepare
Design
&
Build
Run
&
Engage

12. API
Strategy
Plan
&
Prepare
Design
&
Build
Run
&
Engage
Plan
&
Prepare

13. As
primeiras
decisões
de
design…

14. Selecione
a
Tecnologia
Adequada
RESTSOAP vs.

15. Selecione
a
Tecnologia
Adequada
JSONXML vs.

16. and the winners are…
REST + JSON

17. 1Proposta
de
Valor

18. “Você
pode
até
passar
batom
num
porco,
mas
ele
conSnuará
sendo
um
porco!”

19. API
Strategy
Plan
&
Prepare
Design
&
Build
Run
&
Engage
Design
&
Build
Muitos
projetos;
Equipe
pequena
Design
&
Build

20. 2Design
RESTful

21. REST
RepresentaKonal
State
Transfer
EsKlo
arquitetural
criado
por
Roy
Fielding
RESTful
Design
que
respeita
os
conceitos
REST

22. Coleção
/pedidos!
Resources
Elemento
/pedidos/{id}!

23. /getAccount!
/getAllAccounts!
/createDirectory!
/updateGroupName!
/findClientById!
RPC?

24. GET
POST
PUT
DELETE

25. Método
de
Consulta
GET /vendas/pedidos!
GET /checklist/item/4!
GET!
POST!
PUT!
DELETE!
PATCH!

26. Método
para
“Criação”
POST /clientes/98W3G32K01/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!

27. GET!
POST!
PUT!
DELETE!
PATCH!
Método
para
“Atualização”
PUT /clientes/98W3G32K01/enderecos/1!
{!
"endereco": "Av. Brigadeiro Faria Lima",!
"numero": "3820",!
"complemento": "19o. Andar",!
"bairro": "Itaim Bibi",!
"cidade": "São Paulo",!
"estado": "SP",!
"cep": "04538-132"!
}

28. GET!
POST!
PUT!
DELETE!
PATCH!
Método
para
“Remoção”
DELETE /pedidos/{id}!
DELETE /users/98W3G32K01/photos!

29. GET!
POST!
PUT!
DELETE!
PATCH!
Método
para
“Atualização
parcial”
PATCH /users/98W3G32K01 !
{!
"email": "joao.silva@empresa.com"!
}
PATCH /pedidos/39009186!
{!
"status": "Cancelado"!
}

31. 3Versionamento

32. v1
v2
v3
v4
v5
v6
v7
THINGS
CHANGE!

33. 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
alternaKvas:
• Twilio:
/2010-­‐04-­‐01/Accounts/
• Salesforce.com:
/services/data/v20.0/sobjects/Account

34. 4Error
Handling

35. 200!
400!
500!
Resultado
OK
Erro
no
Client
Erro
no
Server

36. STATUS
OK 200!

37. 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!
}!
]!

38. 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!
} !

39. 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!
}!

40. 200!
!
!
400!
!
!
500!
Status
&
Error
Codes
Outros
Comuns
401!
!
403!
404!
!
413!
!
429!
Unauthorized
Forbidden
Not
Found
Request
is
too
Large
Too
Many
Requests

41. 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”!
} !
hMp://en.wikipedia.org/wiki/List_of_HTTP_status_codes

42. Mais
informações?
Vídeo
do
Webinar
hdp://downloads.sensedia.com/webinar-­‐design-­‐de-­‐apis-­‐resful

43. 5Segurança

44. v Acesso
não
autorizado
v Ataques
v Sobrecarga
v Confidencialidade
v Implementações
desastradas
de
clients

45. v Acesso
não
autorizado
v Ataques
v Sobrecarga
v Confidencialidade
v Implementações
desastradas
de
clients

46. þ Identificar App (?)
þ Identificar Usuário (?)
þ Identificar Device (?)
Identidade e
Autorização

47. HTTPS,
sempre!

48. 6Hypermedia

49. Hypermedia
APIs
*POX
=
Plain
Old
XML,
Richardson
Maturity
Model
HATEOAS
=
Hypermedia
as
the
Engine
of
ApplicaKon
State

50. GET /items?q=macbook+air+new
{!
"results" : [ !
{!
"id" : 123,!
"name" : "Macbook Air 2010 LIKE NEW", !
"price" : "499" !
}!
]!
}
SEM
Hypermedia

51. 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"
}!
]!
}

52. API
Strategy
Plan
&
Prepare
Design
&
Build
Run
&
Engage
Run
&
Engage
Muitos
projetos;
Equipe
pequena
Run
&
Engage

53. 7Developers
Portal

54. Docs
incompletos,
desatualizados,
estáScos
e
com
PDFs
de
100
páginas

55. Gekng
Started
www.twilio.com/docs!

56. Documentação
InteraSva
desenvolvedores.extra.com.br!

57. Exemplos
de
código
na
linguagem
do
developer
sendgrid.com/docs!

58. 8Self-­‐Service

59. Sign-­‐up
e
Tokens
de
acesso
automáScos
stripe.com/docs!

60. REST
Console
ou
Sandbox
/
Playgroung
dev.transparencia.org.br!

61. 9Confiabilidade

63. Confiabilidade
Bugs
Problemas
de
Performance
Indisponibilidade
Mudanças
(não-­‐planejadas)
Falta
de
Suporte

64. www.sensedia.com/br!
Trace
de
calls,
Monitoramento,
Rate
LimiSng
e
Alertas

65. status.aws.amazon.com!
Status
Page,
Release
Notes,
Blog

66. Foruns
de
discussão
e
Abertura
de
Sckets
desenvolvedores.extra.com.br!

67. 10Divulgação

68. Hackathon
&
Open
InnovaSon

69. 1 Apps
criadas:
300+
2 Developers
cadastrados:
800+
3 Tráfego:
20M
calls
/
15
dias
4 Eleições
mais
transparentes!
(ou
não)

70. API
Strategy
Plan
&
Prepare
Design
&
Build
Run
&
Engage
1
2 3 4
5 6
7 8 9
10

71. Design
RESTful
2
1 Proposta
de
Valor
3 Versionamento
4 Error
Handling
5 Segurança
7 Developers
Portal
6 Hypermedia
8 Self-­‐Service
9 Confiabilidade
10 Divulgação

72. www.linkedin.com/groups/API-­‐Web-­‐Services-­‐Brasil-­‐5000376
www.meetup.com/API-­‐Craoers-­‐Brasil/

74. Kleber
Bacili
kleber.bacili@sensedia.com
@kleberbacili
10
atributos
de
uma
API
de
sucesso
www.slideshare.net/kleberbacili/