Apresentação realizada no QCon Rio, dia 25/Setembro/2014. #QConRio #APIs #Sensedia Descrição: Impulsionadas pelo aumento da mobilidade, cloud, mídias sociais e internet das coisas, as APIs estão realmente entrando no dia-a-dia das equipes de desenvolvimento – seja de startups que estão começando a desenvolver seus produtos; seja de grandes empresas, que carregam um grande legado de sistemas e investimentos realizados em middlewares de integração. Diversas razões podem levar uma empresa ou desenvolvedor a expor APIs. Mas seja qual for o motivo, alguns cuidados são imprescindíveis para que tragam os resultados esperados. Entretanto, muitas implementações de APIs RESTful não têm levado em consideração princípios básicos de design. Nessa palestra apresentamos atributos de APIs de sucesso, incluindo a proposição de valor de uma API e o entendimento do público-alvo, assim como o design RESTful de resources (URIs, verbos, filtros e paginação). Também são explorados modelos de segurança e o padrão OAuth 2.0; versionamento e formas de documentação; caching de requisições; hipermídia e callbacks; padronização de erros e status codes; controles e medidas recomendadas; além do "onboarding", que inclui divulgação e formas de engajamento.

1. Kleber
Bacili
kleber.bacili@sensedia.com
@kleberbacili
slideshare.net/kleberbacili
10
atributos
de
uma
API
de
sucesso
Do
design
RESTful
e
segurança,
a
formas
de
divulgação
e
engajamento

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

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

4. Contextualização

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

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

7. The
Internet
of
Things

9. 10 Atributos
de
uma
API
de
sucesso

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

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

12. As
primeiras
decisões
de
design…

13. Selecione
a
Tecnologia
Adequada
SOAP vs. REST

14. Selecione
a
Tecnologia
Adequada
XML vs. JSON

15. and the winners are…
REST + JSON

16. 1 Proposta
de
Valor

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

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

19. 2 Design
RESTful

20. REST
RepresentaMonal
State
Transfer
EsMlo
arquitetural
criado
por
Roy
Fielding
RESTful
Design
que
respeita
os
conceitos
REST

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

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

23. GET
POST
PUT
DELETE

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

25. 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!

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

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

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

30. 3 Versionamento

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

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

33. 4 Error
Handling

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

35. STATUS
OK 200!

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

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

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

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

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

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

42. 5 Segurança

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

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

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

46. HTTPS,
sempre!

47. 6 Hypermedia

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

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

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

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

52. 7 Developers
Portal

53. Docs
incompletos,
desatualizados,
estáOcos
e
com
PDFs
de
100
páginas

54. Gehng
Started
www.twilio.com/docs!

55. Documentação
InteraOva
desenvolvedores.extra.com.br!

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

57. 8 Self-­‐Service

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

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

60. 9 Confiabilidade

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

63. www.sensedia.com/br!
Trace
de
calls,
Monitoramento,
Rate
LimiOng
e
Alertas

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

65. Foruns
de
discussão
e
Abertura
de
Ockets
desenvolvedores.extra.com.br!

66. 10 Divulgação

67. Hackathon
&
Open
InnovaOon

68. 1 Apps
criadas:
300+
2 Developers
cadastrados:
800+
3 Tráfego:
20M
calls
/
15
dias
4 Eleições
mais
transparentes!

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

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

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

73. Kleber
Bacili
kleber.bacili@sensedia.com
@kleberbacili
slideshare.net/kleberbacili