Zusammenfassung der Ressource
Melhores Práticas API REST
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- Trabalhanbdo com erros
- 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
- 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
- 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
- Autenticação
- (VER MAPA MENTAL "Mellhores praticas REST API - Autenticação")