Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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/

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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:

Slide 13

Slide 13 text

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:

Slide 14

Slide 14 text

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)

Slide 15

Slide 15 text

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).

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

Django Rest Framework

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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.

Slide 28

Slide 28 text

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.

Slide 29

Slide 29 text

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}

Slide 30

Slide 30 text

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.

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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.

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

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.

Slide 37

Slide 37 text

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.

Slide 38

Slide 38 text

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