Share
Embed
Boas práticas em REST APIs
Conceitos sobre HTTP/RESTful e algumas boas práticas de como projetar sua API de forma consistente e legível.
Diego Garcia
July 16, 2015
Transcript
38 slides
-
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). -
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 -
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 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.