O documento explora o conceito de API (Interface de Programação de Aplicações), suas práticas recomendadas, incluindo RESTful e versionamento. Destaca a importância da padronização nas respostas, segurança, e a relevância da documentação para desenvolvedores. Também menciona métodos de autenticação e fornece dicas para criar respostas eficazes e informativas.

1. APIs: o que são, onde vivem e
como se alimentam

2. O que é uma API?
a.k.a. Application Programming Interface
2
1.

3. Interface
E nada mais.
Mesmo.
3
Uma Sistema
API
Sistema /
Serviço

4. Boas práticas, RESTful e outras
histórias
Pelo bem de todos os devs
4
2.

5. RESTful
» REST: REpresentational State Transfer
» Requisições e respostas via HTTP
» As transações são identificadas via métodos: GET, POST, PUT,
PATCH, DELETE
» Cada recurso deve ter sua própria URL
» Os recursos devem ser diferenciados por IDs
» Stateless
GET http://www.aquelaurlmarota.com/users/12345/orders
5

6. Status codes
Toda resposta traz um status code
» 2xx: 200, 201, 204… SUUUCESSOOOOO!
» 3xx: 302, 304… redirecionamentos
» 4xx: 400, 401, 403, 404… erros client side
» 5xx: 500… erros server side
http://http.cat/
6

7. Versionamento
» Exponha só a versão cheia (/v1/users ou /v2/users)
» Evite breaking changes:
- renomear campos
- remover recursos
- remover campos
- remover endpoints
7

8. Padronização
» Padronize as respotas: json, xml?
» Consistência entre os diferentes endpoints
» Status codes
» Cabeçalhos só quando realmente necessário
8

9. Dicas para montar uma resposta decente
» Wrap de resposta:
{
”data”: {
”nome”: ”diana”,
”cor”: ”vermelho”
}
}
9

10. Dicas para montar uma resposta decente
» Ao retornar um erro, mostre código E descrição
{
”errorCode”:123,
”errors”: [
”special characters are not alowed”,
”user CPF is required”
]
}
» NUNCA exponha erros internos ao usuário
10

11. Segurança
» Não exponha IDs sequenciais
» Limite de requisições por segundo
» SEMPRE use https
» Não use logins por senha
11

12. Documentação
O coração de uma boa API
12
3.

13. Documentação
» ”Uma API só é tão boa quanto sua documentação”
(apiary.io)
» Quem consome? Desenvolvedores, não máquinas
» Sugestão: swagger (http://swagger.io/)
» Documentation First
» EMPATIA
13

14. Autenticação
Login e senha NÃO
14
4.

15. Autenticação
» OAuth 2.0
- segue um fluxo de autorização
» JWT
- utiliza tokens de autenticação
15

16. Diana Arnos
Tech daimyo @ high stakes
academy
twitter: dianaarnos
facebook: dianaarnos
github: dianaarnos
instagram: dianaarnos
16OBRIGADA!

17. CREDITS
Special thanks to all the people who made and released these awesome
resources for free:
» Presentation template by SlidesCarnival
» Photographs by Unsplash
» Diverse device hand photos by Facebook Design Resources
17