Melhores Práticas API REST_2

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
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
Autenticação
1. Exemplos de serviços de autenticação utilizados
  1. PayPal Permissions Service API
  2. Facebook OAuth 2.0
  3. Twitter OAuth 1.0a
2. Toda chamada REST deve ser executada usando ssl (https), pois evita ataques do tipo man in the midle
3. Toda chamada deve ocorrer com chaves de API dedicadas
4. Todas chamadas REST devem ser autenticadas
5. Tipos de autenticação
  1. Http Básica (Authtype basic)
    1. Utiliza a autenticação do apache, onde é configurado 'basic' e com utilização de arquivo de senha ou senhas gerenciadas pela aplicação
    2. Vantagens
      1. Está disponível desde o Http 1.0
      2. Api mantém apenas hashes
    3. Desvantagens
      1. Depende da configuração do webserver
      2. Nome do usuário e senha são transmitidos via base64
  2. Autenticação de resumo (AuthType digest)
    1. Possui 2 elementos a mais do que a básica
      1. NONCE: string passada pela api para o cliente que deve ser enviada junto à requisição
      2. qop: verificador de qualidade de proteção
    2. Vantagens
      1. Senhas protegidas, utiliza troca de hash
      2. Http 1.0
      3. Utiliza NONCE e CNONCE, estes protegem contra ataques de ataque repetido, pois possui sincronismo entre api/cliente e também contra inserção de textos manipulados
    3. Desvantagens
      1. Complexidade maior que a básica
      2. Toda requisição deve passar pelo desafio (duplica cada requisição)
      3. Vulnerável a apis forjadas
6. A autenticação funciona como um selo de autenticidade que é enviado jungo com cada chamada
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

Next up

Melhores Práticas API REST_2

Description

Resource summary

Similar

	Created by Edvaldo Ribeiro about 10 years ago

	Copied by Edvaldo Ribeiro about 10 years ago