Melhores Práticas API REST

edvaldo2107
Mind Map by edvaldo2107, updated more than 1 year ago
edvaldo2107
Created by edvaldo2107 almost 6 years ago
74
0

Description

Baseado no apigee
Tags

Resource summary

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

Similar

Core Spring 4.2 Certification Mock Exam
antoine.rey
RESTful Web Services with Express Framework and mongoose.
Angel Martínez Rodriguez
ASSIGNMENT SHEET 2-1-3: BASIC THEORY REVIEW
Justin Vaughan
/service/rest/login/reset/:account
Nikolaos Grammatikos
HW Image API
danh1964
testing
Milka Milkonska
FHIR
R A
.NET Web API
Pritesh Patel
Core Spring 4.2 Certification Mock Exam
Abdullah G
Spring 4.2 Certification Mock Exam
Karthikeyan Vaithilingam