Boas Boas práticas práticas em em REST APIs REST APIs 

Diego Garcia Diego Garcia /author/diego-garcia.html http://codeforcloud.info/ drgarcia1986 @drgarcia1986 /drgarcia1986 

HTTP e REST HTTP e REST ● HTTP é um protocolo de requisição- resposta. ● REST é um conjunto de princípios que definem como HTTP e URIs devem ser usados. HTTP: Hypertext Transfer Protocol REST: Representational State Transfer 

GET /products/ HTTP/1.1 User-Agent: curl/7.35.0 Host: localhost:5000 Accept: */* Request Request curl -v localhost:5000/products/ 

GET /products/ HTTP/1.1 User-Agent: curl/7.35.0 Host: localhost:5000 Accept: */* Request Request curl -v localhost:5000/products/ VERBO VERBO 

GET /products/ HTTP/1.1 User-Agent: curl/7.35.0 Host: localhost:5000 Accept: */* Request Request curl -v localhost:5000/products/ URI URI 

GET /products/ HTTP/1.1 User-Agent: curl/7.35.0 Host: localhost:5000 Accept: */* Request Request curl -v localhost:5000/products/ Formatos aceitos Formatos aceitos 

HTTP/1.1 200 OK CONTENT-TYPE: application/json CONTENT-LENGTH: 83 [{"name":"smartphone","price":500.0, "id":1}, {"name":"tablet","price":300.0,"id":2}] Response Response curl -v localhost:5000/products/ 

HTTP/1.1 200 OK CONTENT-TYPE: application/json CONTENT-LENGTH: 83 [{"name":"smartphone","price":500.0, "id":1}, {"name":"tablet","price":300.0,"id":2}] Response Response curl -v localhost:5000/products/ Status Code Status Code 

HTTP/1.1 200 OK CONTENT-TYPE: application/json CONTENT-LENGTH: 83 [{"name":"smartphone","price":500.0, "id":1}, {"name":"tablet","price":300.0,"id":2}] Response Response curl -v localhost:5000/products/ Formato da resposta Formato da resposta 

HTTP/1.1 200 OK CONTENT-TYPE: application/json CONTENT-LENGTH: 83 [{"name":"smartphone","price":500.0, "id":1}, {"name":"tablet","price":300.0,"id":2}] Response Response curl -v localhost:5000/products/ Corpo da resposta Corpo da resposta 

Verbos Verbos ● GET: Ler um recurso ou uma coleção. ● POST: Criar um recurso. ● PUT: Atualizar um recurso. ● PATH: Atualizar um recurso. ● DELETE: Apagar um recurso. Mais comuns: 

Códigos de retorno Códigos de retorno ● 200: OK. ● 201: Created. ● 204: No Content. ● 400: Bad Request. ● 401: Unauthorized. ● 403: Forbidden. ● 404: Not Found. ● 405: Method not allowed. ● 409: Conflict. ● 500: Internal Server Error. Mais comuns: 

Cabeçalhos Cabeçalhos ● Verbo: Tipo da operação (ex. GET) (req). ● URI: Identificação do resource (ex. /person) (req). ● Content-Type: Formato do corpo (ex. application/json) (req/res). ● Authorization: Credenciais (ex. Token foo) (req). ● Etag: Hash de identificação de um resource (ex “737060cd8”) (res). ● X-: Experimental (ex: x-acme-session) (req/res) 

Resources Resources ● Uma instancia (ou uma coleção) de um objeto (ex: products). ● Acessível através de um endpoint (ex: /products/8d2624365). ● Suas operações são determinadas através dos verbos (ex: GET /products/). ● Podem possuir relacionamentos. ● Podem possuir diferentes representações (ex: JSON, YAML, XML). 

Como Como frameworks frameworks resumem tudo resumem tudo isso? isso? 

Django Rest Framework 

Onde está o Onde está o Verbo HTTP ? Verbo HTTP ? Django Rest Framework 

Onde está o Onde está o Verbo HTTP ? Verbo HTTP ? Onde está o Onde está o Status Code ? Status Code ? Django Rest Framework 

Onde está o Onde está o Verbo HTTP ? Verbo HTTP ? Onde está o Onde está o Status Code ? Status Code ? O que diabos O que diabos isso faz ? isso faz ? Django Rest Framework 

No content

Algumas Algumas Boas Práticas Boas Práticas Parar criar uma API que chuta bundas Parar criar uma API que chuta bundas 

HTTP HTTP ● Uso correto dos verbos. ● Uso correto dos status code. ● Uso correto dos cabeçalhos. Isso é basicamente REST 

Use Use nomes nomes no Plural no Plural ● Procure nomear seus resources no plural: – /products /products, /persons /persons, , /customers /customers ● Se preferir o singular, mantenha tudo no singular. ● NUNCA misture os dois: – /product /product, /person /person, , /customers /customers 

Use o Use o verbo verbo no no protocolo, protocolo, não não na na url url ● Fuja de urls com verbos: – /getProducts /getProducts, / /createProducts createProducts ● Use o verbo no protocolo HTTP: – GET GET /products /products, POST POST /products /products ● Seja REST, não RPC. RPC: Remote Procedure Call 

Deixe a complexidade Deixe a complexidade para a query string para a query string ● Filtros, pesquisas e paginação devem ficar na query string: – /products?color=red&type=mobile /products?color=red&type=mobile ● Não complique sua base de urls: – /products/redAndMobile /products/redAndMobile 

Ações devem ser REST Ações devem ser REST ● Não quebre padrões para ações: – /machine/{id}/turnOn /machine/{id}/turnOn – /machine/{id}/turnOff /machine/{id}/turnOff ● Use os verbos HTTP e deixe explícito que se trata de uma ação: – POST /machine/{id}/action/turn POST /machine/{id}/action/turn (turn on) – DELETE /machine/{id}/action/turn DELETE /machine/{id}/action/turn (turn off) ● Se sua API tem muitas ações, talvez você deva usar RPC. 

Não exponha seus IDs Não exponha seus IDs ● Evite ao máximo ids sequenciais: – /persons/1 /persons/1 – /persons/2 /persons/2 ● Use UUIDs sempre que possível: – /persons/59988232-29d0-11e5-848c- /persons/59988232-29d0-11e5-848c- 1078d2624365 1078d2624365 – /persons/ /persons/ ??? ● Isso é uma questão de segurança. 

Simplifique Simplifique os os múltiplos múltiplos relacionamentos relacionamentos ● Limite as urls a até dois níveis: – /artists/{id}/albums/{id} /artists/{id}/albums/{id} ● Se necessário, crie atalhos: – /artists/{id}/albums/{id}/tracks/{id}/... /artists/{id}/albums/{id}/tracks/{id}/... – /albums/{id} /albums/{id} – /tracks/{id} /tracks/{id} 

Autenticação Autenticação ● Não invente o seu próprio sistema maluco de autenticação. ● Use um protocolo já conhecido e testado pela comunidade. ● De preferencia para o OAuth2, por sua vasta documentação e seus diversos casos de sucesso. 

Quando você inventa o Quando você inventa o seu próprio sistema de seu próprio sistema de autenticação autenticação 

É assim que os clientes É assim que os clientes da API reagem da API reagem 

Erros devem ser Erros devem ser compreensíveis compreensíveis ● Respeite os status code HTTP. ● Forneça uma descrição do erro para o desenvolvedor. ● Forneça uma descrição do erro para o usuário final (caso seja necessário). ● Forneça um link para a documentação onde trata do erro ocorrido. 

Erros devem ser Erros devem ser compreensíveis compreensíveis 

Erros devem ser Erros devem ser compreensíveis compreensíveis Caso seja mais de um erro, considere retornar uma lista com todos os erros ocorridos no request 

Considere o cache Considere o cache ● Esteja sempre pronto para fazer cache de seus responses. ● Os cabeçalhos ETag e If-None-Match podem ser úteis. ● NUNCA guarde estado em suas APIs, use o redis ou o memcached para isso. 

Documentação Documentação ● Uma boa API deve possuir uma excelente documentação. ● Disponibilize exemplos de consumo da API (de preferência baseados no cURL). curl -X POST -H 'Content-Type: curl -X POST -H 'Content-Type: application/json' -d '{“foo”: “bar”}' application/json' -d '{“foo”: “bar”}' https://fun.com/api/foo https://fun.com/api/foo ● Disponibilize um ambiente de sandbox. 

Muito Muito obrigado! obrigado! [email protected] https//twitter.com/drgarcia1986