O documento aborda os 10 atributos essenciais para o sucesso de APIs com design RESTful, incluindo planejamento, segurança, versionamento e manejo de erros. Destaca a importância de estratégias adequadas, documentação clara e o engajamento de desenvolvedores. Também menciona a necessidade de abordagens educativas e de promoção, como hackathons, para estimular a inovação e a transparência.

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