Boas práticas de API design

Boas práticas de API design

Nestes slides apresento dicas de Design de API, que são algumas boas práticas para construir APIs REST.

A444e1ba503ea1e02bb007a4f92df8c1?s=128

Caio Ribeiro Pereira

March 12, 2015
Tweet

Transcript

  1. 2.

    About me • 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)
  2. 3.

    Tópicos a discutir… • 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
  3. 4.

    Versionamento de APIs • 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)
  4. 5.

    Definição de endpoints • 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}
  5. 6.

    Definição de endpoints • 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
  6. 7.

    Definição de endpoints • 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
  7. 8.

    Métodos do HTTP • 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
  8. 9.

    Status do HTTP • 2xx - Status de sucesso
 3xx

    - Status de redirecionamento
 4xx - Status de erro no cliente
 5xx - Status de erro no servidor • Exemplos de status mais utilizados: • 200 - OK, 201 - Created, 204 - No Content • 404 - Not Found, 401- Unauthorized, 405 - Method Not Allowed • 412 - Precondition Failed, 411 - Length Required, 408 - Request Timeout • 500 - Internal Server Error, 501 - Not Implemented • Veja mais status em: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html • Dica: Padronize sua API para usar entre 7-12 status codes.
  9. 10.

    JSON de resposta Retornando um objeto
 {
 “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. Retornando objetos relacionados
 {
 “code”: “12312cA”,
 “nome”: “João”,
 “compra”: {
 “code”: “13333A”,
 “valor”: 10.00 
 }
 }
  10. 11.

    Tratamento de erros • Retorne JSON de erros
 Erros genéricos


    {
 “code”: “0001",
 “message”: “Acesso negado!”
 }
 
 Erros de campos específicos
 {
 “code”: “0002”,
 “errors”: [
 {“nome”: [“Nome em branco”]},
 {“idade”: [“Idade em branco”, “Você é menor de idade”]}
 ]
 } • 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
  11. 12.

    Dicas de seguranç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
  12. 14.

    Ferramenta para documentação de APIs ApiDoc.js
 http://apidocjs.com
 Gera documentação em

    cima de comentários no có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!"}); });
  13. 16.

    Considerações finais • 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