Melhores Práticas API REST

Melhores Práticas API REST

1. Substantivos são bons e verbos são ruins

   • Use somente os substantivos nas urls e deixe a ação para os tipos (verbos Http) de envio (POST, GET, PUT, etc). Ex: GET /users/34 retorna o usuário 34, PUT /users/34 atualiza o usuário 34
     • GET – solicitar recursos;
     • POST – criar recursos;
     • PUT – atualizar um recurso por completo;
     • PATCH – atualizar parte de um recurso;
     • DELETE – excluir um recurso
     • OPTIONS – utilizado por apps front-end para saber quais métodos estão disponíveis na nossa API
   • Utilizar os substantivos no plural e mais intuitivo
   • Utilize 2 url's base por recurso. Ex /users e /users/2

2. Nomes concretos são melhores do que nomes abstratos

   • Por exemplo, chamar por /itens trará dados de videos, textos e imagens, então item abstrai todo o conteúdo de retorno
   • O nível de abstração depende do cenário

3. Simplifique as associações

   • Por exemplo: GET /departments/35/users trás os usuários do departamento 35, POST /departments/35/users insere um novo usuário no departamento 35
   • Não há necessidade de se ter uma url muito extensa quando há muitos relacionamentos, pois será passado a chave primária do penúltimo pai, então o ideal e seguir o seguinte exemplo: POST /departments/35/users

4. Mantenha intuitiva a api jogando a complexidade de parâmetros e associação entre recursos para query string da url

   • Exemplo: Pegar todos os cachorros vermelhos correndo no parque -> GET /dogs?color=red&state=running&location=park

5. Versione sempre sua API

   • Utilize o identificador de versão e o número da mesma. Ex: v1, v2
   • Sempre passe a versão da API que está utilizando ao consumi-la, para evitar erros de compatibilidade quando a mesma for atualizada
   • Exemplos de versionamento
     • Facebook: ?v=1.0
     • Twilio: /2010-04-01/Accounts/
     • Salesforce.com: /services/data/v20.0/sobjects/Account

6. Paginação e respostas parciais

   • Exemplos de respostas parciais:
     • Linkedin: /people:(id,first-name,last-name,industry)
     • Facebook: /joe.smith/friends?fields=id,name,picture
     • Google: ?fields=title,media:group(media:thumbnail)
   • Exemplos de Offset e Limit
     • Facebook - offset 50 and limit 25
     • Twitter - page 3 and rpp 25 (records per page)
     • LinkedIn - start 50 and count 25

7. Respostas que não envolve recursos

   • Respostas sem recursos são requisições que não interagem com banco de dados, apenas chama algum método que retorna a execução de algum algorítmo
   • Utilize verbos ao invés de substantivos
   • Ex: converter 100 reais para dolar - /convert?from=REAL&to=DOLAR&amount=100

8. Suporte a vários formatos

   • Exemplos de definição de respostas
     • Google Data: ?alt=json
     • Foursquare: /venue.json
     • Digg: Accept: application/json ?type=json
   • É importante possibilitar a API trabalhar com vários formatos: JSON, XML, ETC

9. Nomes de atributos de request/response

   • Exemplos
     • Twitter - "created_at": "Thu Nov 03 05:19;38 +0000 2011"
     • Bing - "DateTime": "2011-10-29T09:35:00Z"
     • Foursquare - "createdAt": 1320296464
   • Recomendações
     • Utilize o padrão da linguagem Javascript para json
     • CamelCase para atributos
     • Utilize maiúsculo e minúsculo dependendo do tipo de objeto

10. Truques para buscas

    • Exemplos
      • Busca Global: /search?q=fluffy+fur
      • Busca com escopo: /owners/5678/dogs?q=fluffy+fur
      • Busca com resultados formatados: /search.xml?q=fluffy+fur

11. Trabalhanbdo com erros

12. Consolidar requisições de API em um subdomínio

    • Exemplos
      • Facebook possui duas apis: graph.facebook.com api.facebook.com
      • Foursquare possui uma API: api.foursquare.com
      • Twitter possui 3 API'S: stream.twitter.com api.twitter.com search.twitter.com
    • Utilizado para separar mais de uma api ou para simplificar a url

13. Dicas para trabalhar com comportamento de exceções

    • Utilize uma opção no parâmetro para suprir o status de retorno do cabeçalho, caso o desenvolvedor queira, para que retorne sempre 200 (Padrão utilizado pelo twitter). Ex: /public_timelines.json? suppress_response_codes=true
    • Permita igonar o status de retorno, retornando sempre 200 (OK)
    • Quando o cliente suportar métodos Http limitados utilize o tipo de método opicional como parâmetro
      • Ex: Create /dogs?method=post
      • Read /dogs
      • Update /dogs/1234?method=put&location=park
      • Delete /dogs/1234?method=delete

14. Princípios REST

    • Para uma API ser REST ela deve ser statless, ou seja, é totalmente alheia ao estado de aplicação, cada requisição é isolada e deve ser passada todas informações necessárias para obter um retorno
    • API não utiliza sessão
    • API não utiliza cookies
    • Para armazenar informações e estado da API no cliente, usa-se web storage, local storage ou session storage
      • Session storage: mesmo estado da API em mais páginas de uma aplicação
      • Local Storage: Para manter informação a longo prazo, ex: de um dia para o outro

15. Autenticação

    • (VER MAPA MENTAL "Mellhores praticas REST API - Autenticação")