O documento discute boas práticas de design de APIs, incluindo versionamento de APIs, definição de endpoints, status HTTP, tratamento de erros e ferramentas de documentação de APIs.

1. BoaspráticasdeAPIDesign
Caio Ribeiro Pereira
@crp_underground
http://crpwebdev.com
http://udgwebdev.com

2. Aboutme
• Web Developer na Concrete Solutions
• Blogueiro no udgwebdev.com
• Autor dos livros de Node.js/Meteor na Casa do Código
• Projetos
• DevFreeCasts (devfreecasts.org)
• DevFreeBooks (devfreebooks.org)

3. Tópicosadiscutir…
• Versionamento de APIs
• Definição de endpoints
• Métodos do HTTP
• Status do HTTP
• JSON de resposta
• Tratamento de erros
• Dicas de segurança
• Ferramenta para documentação de APIs
• Considerações finais

4. VersionamentodeAPIs
• Exemplos de versionamento:
• url: api.com/v1/endpoint (via código da API)
• subdomain: v1.api.com/endpoint (via DNS)
• header: “Accept”=“application/vnd.api.v1.json” (via Middleware)

5. Definiçãodeendpoints
• Criando endpoints:
• Listando clientes
/clientes
• Visualizando um cliente
/clientes/{cliente_id}
• Executando uma ação de recurso
/clientes/{cliente_id}/login
• Visualizando uma determinada compra de um cliente
/clientes/{cliente_id}/compras/{compra_id}

6. Definiçãodeendpoints
• Organizando endpoints:
• Evite muitos “encadeamento" de endpoints:
• /clientes/1/compras/2/items/3
• Mantenha no máximo um duplo encadeamento de endpoints:
• /clientes/1/compras/2
• /compras/2/items/3
• Utilize nomes em plural para recursos e verbos para ações:
• /clientes/1/login

7. Definiçãodeendpoints
• Use querystrings para seleção de campos, ordenações e paginações:
• Paginando
/clientes?offset=10&limit=2
/clientes?page=10&limit=2
/clientes?page=10&per_page=2
• Ordenando
/clientes?sort=nome
• Selecionando campos
/clientes?fields=nome,idade
• Tudo junto!
/clientes?offset=10&limit=2&sort=nome&fields=nome

8. MétodosdoHTTP
• GET/clientes - Lista todos os clientes
• GET/clientes/1 - Visualiza um cliente
• POST/clientes - Cadastra um novo cliente
• PUT/clientes/1 - Atualiza todos os dados do cliente
• PATCH/clientes/1- Atualiza alguns dados do cliente
• DELETE/clientes/1- Exclui um cliente

9. StatusdoHTTP
• 2xx-Statusdesucesso
3xx-Statusderedirecionamento
4xx-Statusdeerronocliente
5xx-Statusdeerronoservidor
• Exemplos de status mais utilizados:
• 200-OK,201-Created,204-NoContent
• 404-NotFound,401-Unauthorized,405-MethodNotAllowed
• 412-PreconditionFailed,411-LengthRequired,408-RequestTimeout
• 500-InternalServerError,501-NotImplemented
• Veja mais status em: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
• Dica: Padronize sua API para usar entre 7-12 status codes.

10. JSONderesposta
Retornandoumobjeto
{
“code”:“12312cA",
“nome”:“João",
“idade”:18
}
Use UUID como id de objetos (campo code), evite id de banco de dados.
Evite retornar objetos que não estejam em relacionamento, neste caso crie
endpoints específicos para retornar cada um desses objetos.
Retornandoobjetosrelacionados
{
“code”:“12312cA”,
“nome”:“João”,
“compra”:{
“code”:“13333A”,
“valor”:10.00
}
}

11. Tratamentodeerros
• Retorne JSON de erros
Erros genéricos
{
“code”:“0001",
“message”:“Acessonegado!”
}
Erros de campos específicos
{
“code”:“0002”,
“errors”:[
{“nome”:[“Nomeembranco”]},
{“idade”:[“Idadeembranco”,“Vocêémenordeidade”]}
]
}
• Utilize corretamente os códigos 4xx ou 5xx do HTTP para definir seu respectivo status do erro.
• Não é obrigatório! Mas trabalhar com códigos de erros internos é uma boa prática também

12. Dicasdesegurança
• Implemente OAuth para clientes consumirem sua api
• Habilite o CORS (Cross-Origin Resource Sharing) para controlar acesso aos
recursos
• Evite o uso de Tokens estáticos para acesso a api

13. FerramentaparadocumentaçãodeAPIs
Swagger
http://swagger.io
Permitetrabalharcommockseéserverself-hosted

14. FerramentaparadocumentaçãodeAPIs
ApiDoc.js
http://apidocjs.com
Geradocumentaçãoemcimadecomentáriosnocódigo
/**
* @api {get} /signin Singin
* @apiGroup Sistema
*
* @apiSuccess {String} status Mensagem de acesso autorizado
*
* @apiSuccessExample {json} Sucesso
* HTTP/1.1 200 OK
* {
* "status": "Logado!"
* }
*
*/
app.get("/signin", function(req, res) {
res.json({status: "Logado!"});
});

15. FerramentaparadocumentaçãodeAPIs
Apiary
http://apiary.io
SaaS,documentaçãoemmarkdownetrabalhacommocks

16. Consideraçõesfinais
• Crie versões client (consumers) que abstraia complexidade do consumo da
api para algumas ou as principais linguagens programação.
Exemplos: api-client-node, api-client-java, api-client-ruby…
• APIs de referência para estudos…
• Heroku: https://devcenter.heroku.com/categories/platform-api
Github: https://developer.github.com/v3
Twitter: https://dev.twitter.com/rest/public
Facebook: https://developers.facebook.com
• MarketPlace com várias APIs públicas: http://www.publicapis.com

17. Obrigado!
THEEND