Melhores Práticas API REST

Substantivos são bons e verbos são ruins
1. 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
  1. GET – solicitar recursos;
  2. POST – criar recursos;
  3. PUT – atualizar um recurso por completo;
  4. PATCH – atualizar parte de um recurso;
  5. DELETE – excluir um recurso
  6. OPTIONS – utilizado por apps front-end para saber quais métodos estão disponíveis na nossa API
2. Utilizar os substantivos no plural e mais intuitivo
3. Utilize 2 url's base por recurso. Ex /users e /users/2
Nomes concretos são melhores do que nomes abstratos
1. Por exemplo, chamar por /itens trará dados de videos, textos e imagens, então item abstrai todo o conteúdo de retorno
2. O nível de abstração depende do cenário
Simplifique as associações
1. 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
2. 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
Mantenha intuitiva a api jogando a complexidade de parâmetros e associação entre recursos para query string da url
1. Exemplo: Pegar todos os cachorros vermelhos correndo no parque -> GET /dogs?color=red&state=running&location=park
Versione sempre sua API
1. Utilize o identificador de versão e o número da mesma. Ex: v1, v2
2. Sempre passe a versão da API que está utilizando ao consumi-la, para evitar erros de compatibilidade quando a mesma for atualizada
3. Exemplos de versionamento
  1. Facebook: ?v=1.0
  2. Twilio: /2010-04-01/Accounts/
  3. Salesforce.com: /services/data/v20.0/sobjects/Account
Paginação e respostas parciais
1. Exemplos de respostas parciais:
  1. Linkedin: /people:(id,first-name,last-name,industry)
  2. Facebook: /joe.smith/friends?fields=id,name,picture
  3. Google: ?fields=title,media:group(media:thumbnail)
2. Exemplos de Offset e Limit
  1. Facebook - offset 50 and limit 25
  2. Twitter - page 3 and rpp 25 (records per page)
  3. LinkedIn - start 50 and count 25
Respostas que não envolve recursos
1. 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
2. Utilize verbos ao invés de substantivos
3. Ex: converter 100 reais para dolar - /convert?from=REAL&to=DOLAR&amount=100
Suporte a vários formatos
1. Exemplos de definição de respostas
  1. Google Data: ?alt=json
  2. Foursquare: /venue.json
  3. Digg: Accept: application/json ?type=json
2. É importante possibilitar a API trabalhar com vários formatos: JSON, XML, ETC
Nomes de atributos de request/response
1. Exemplos
  1. Twitter - "created_at": "Thu Nov 03 05:19;38 +0000 2011"
  2. Bing - "DateTime": "2011-10-29T09:35:00Z"
  3. Foursquare - "createdAt": 1320296464
2. Recomendações
  1. Utilize o padrão da linguagem Javascript para json
  2. CamelCase para atributos
  3. Utilize maiúsculo e minúsculo dependendo do tipo de objeto
Truques para buscas
1. Exemplos
  1. Busca Global: /search?q=fluffy+fur
  2. Busca com escopo: /owners/5678/dogs?q=fluffy+fur
  3. Busca com resultados formatados: /search.xml?q=fluffy+fur
Trabalhanbdo com erros
Consolidar requisições de API em um subdomínio
1. Exemplos
  1. Facebook possui duas apis: graph.facebook.com api.facebook.com
  2. Foursquare possui uma API: api.foursquare.com
  3. Twitter possui 3 API'S: stream.twitter.com api.twitter.com search.twitter.com
2. Utilizado para separar mais de uma api ou para simplificar a url
Dicas para trabalhar com comportamento de exceções
1. 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
2. Permita igonar o status de retorno, retornando sempre 200 (OK)
3. Quando o cliente suportar métodos Http limitados utilize o tipo de método opicional como parâmetro
  1. Ex: Create /dogs?method=post
  2. Read /dogs
  3. Update /dogs/1234?method=put&location=park
  4. Delete /dogs/1234?method=delete
Princípios REST
1. 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
2. API não utiliza sessão
3. API não utiliza cookies
4. Para armazenar informações e estado da API no cliente, usa-se web storage, local storage ou session storage
  1. Session storage: mesmo estado da API em mais páginas de uma aplicação
  2. Local Storage: Para manter informação a longo prazo, ex: de um dia para o outro
Autenticação
1. (VER MAPA MENTAL "Mellhores praticas REST API - Autenticação")

Next up

Melhores Práticas API REST

Description

Resource summary

Similar

	Created by Edvaldo Ribeiro over 10 years ago