0Pricing
R Academy · Aula

Criando endpoints GET e POST

Lide com parâmetros de caminho, strings de consulta e análise do corpo das solicitações.

Criando endpoints GET e POST é uma aula grátis de R Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de R Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de R Academy inclui 4 aulas no total.

O que é o Plumber?

O plumber transforma funções R comuns em pontos de acesso de APIs HTTP usando anotações especiais em comentários. Anote uma função com #* @get /path, e o Plumber criará uma rota GET que chama essa função e retorna o resultado em JSON.

Instale-o com install.packages('plumber').

Seu primeiro ponto de acesso GET

Uma API Plumber básica reside em um arquivo (por exemplo, api.R). Anote a função com #* @get seguido do caminho. O Plumber serializa automaticamente o valor retornado pela função para JSON.

# api.R
# library(plumber)
#
# #* Return a greeting
# #* @get /hello
# function() {
#   list(message = 'Hello from Plumber!')
# }
#
# Start with:
# pr <- plumb('api.R')
# pr$run(port = 8000)

Parâmetros de caminho com indicações de tipo

Insira segmentos variáveis no caminho usando a sintaxe com sinais de menor e maior: /users/<id:int>. O Plumber analisa o segmento e o passa como um argumento tipado para sua função. Os tipos compatíveis incluem int, dbl e chr.

# #* Get a user by ID
# #* @get /users/<id:int>
# function(id) {
#   # id is already an integer
#   list(
#     user_id = id,
#     name    = paste('User', id)
#   )
# }
#
# GET /users/42  =>  {"user_id":42, "name":"User 42"}

Parâmetros de consulta com #* @param

Documente os parâmetros de consulta com #* @param name Description. O nome do parâmetro deve corresponder ao nome do argumento da função. O Plumber o lê automaticamente da cadeia de consulta — não é necessária nenhuma análise manual.

# #* Search users by name
# #* @param name The name to search for
# #* @param limit Maximum results to return
# #* @get /users/search
# function(name = '', limit = '10') {
#   limit <- as.integer(limit)
#   # query string: /users/search?name=Alice&limit=5
#   list(query = name, max = limit)
# }

Criando um ponto de acesso POST

Use #* @post /path para pontos de acesso que recebem um corpo de solicitação. O argumento especial req dá acesso ao objeto de solicitação bruto. O Plumber o passa automaticamente quando o argumento da função se chama req.

# #* Create a new user
# #* @post /users
# function(req) {
#   body <- jsonlite::fromJSON(req$postBody)
#   # body$name, body$email are now available
#   list(
#     status  = 'created',
#     user_id = sample(1000:9999, 1),
#     name    = body$name
#   )
# }

Analisando o corpo da solicitação

req$postBody contém a cadeia JSON bruta do corpo POST. Analise-a com jsonlite::fromJSON(req$postBody) para obter uma lista R nomeada. Sempre valide os campos obrigatórios antes do processamento.

# #* @post /orders
# function(req, res) {
#   body <- jsonlite::fromJSON(req$postBody)
#   if (is.null(body$product_id)) {
#     res$status <- 400L
#     return(list(error = 'product_id is required'))
#   }
#   list(
#     order_id   = as.integer(Sys.time()),
#     product_id = body$product_id,
#     quantity   = body$quantity %||% 1
#   )
# }

Códigos de status HTTP com res$status

O argumento res (também injetado automaticamente pelo Plumber) permite definir o código de status da resposta HTTP. Defina-o antes de retornar: res$status <- 404L. Códigos comuns:

  • 200 — OK (padrão)
  • 201 — Criado
  • 400 — Solicitação inválida
  • 404 — Não encontrado
  • 500 — Erro interno do servidor
# #* @get /items/<id:int>
# function(id, res) {
#   items <- list(
#     list(id=1, name='Widget'),
#     list(id=2, name='Gadget')
#   )
#   found <- Filter(function(x) x$id == id, items)
#   if (length(found) == 0) {
#     res$status <- 404L
#     return(list(error = paste('Item', id, 'not found')))
#   }
#   found[[1]]
# }

Retornando listas nomeadas como JSON

O Plumber serializa os valores retornados por R para JSON usando jsonlite. Listas nomeadas se tornam objetos JSON; listas sem nome se tornam matrizes JSON. Retorne uma lista nomeada para obter respostas estruturadas.

# Named list => JSON object
# list(id=1, name='Alice')  => {"id":1, "name":"Alice"}
#
# Unnamed list => JSON array
# list(1, 2, 3)  =>  [1, 2, 3]
#
# Nested structures work too:
# list(
#   user   = list(id=1, name='Alice'),
#   orders = list(list(id=101), list(id=102))
# )
# => {"user":{"id":1,"name":"Alice"}, "orders":[{"id":101},{"id":102}]}

O objeto roteador do Plumber

Carregue um arquivo R anotado com plumb('api.R') para criar um objeto router do Plumber. Chame pr$run(port = 8000) para iniciar o servidor. Em produção, normalmente você chama pr_run(pr, host='0.0.0.0', port=8000).

# Standard plumber startup in api_start.R:
# library(plumber)
# pr <- plumb('api.R')
# pr$run(port = 8000, host = '0.0.0.0')
#
# Or with pipe style:
# plumb('api.R') |> pr_run(port = 8000)
#
# Test with:
# curl http://localhost:8000/hello

Lidando com vários métodos HTTP

Um único caminho pode aceitar vários métodos por meio da criação de funções anotadas separadamente. O Plumber encaminha as solicitações para a função correta com base no método HTTP usado.

# #* List all products
# #* @get /products
# function() {
#   list(products = list(list(id=1, name='Widget')))
# }
#
# #* Create a product
# #* @post /products
# function(req) {
#   body <- jsonlite::fromJSON(req$postBody)
#   list(created = TRUE, name = body$name)
# }

Testando seus endpoints de API

Use curl no terminal ou httr2 no R para testar endpoints enquanto o servidor está em execução. httr2 permite escrever testes reproduzíveis junto com o código da sua API.

# From terminal:
# curl http://localhost:8000/users/42
# curl -X POST http://localhost:8000/users \
#      -H 'Content-Type: application/json' \
#      -d '{"name":"Alice","email":"alice@example.com"}'
#
# From R:
# library(httr2)
# resp <- request('http://localhost:8000/users/42') |> req_perform()
# resp_body_json(resp)

Verificação rápida: parâmetros de caminho

Como declarar um parâmetro de caminho chamado id que o Plumber deve analisar como um inteiro?

Recapitulação de endpoints GET e POST

Criando endpoints REST com o Plumber:

  • #* @get /path cria uma rota GET; #* @post /path cria uma rota POST
  • Os parâmetros de caminho usam a sintaxe <name:type> (int, dbl, chr)
  • Os parâmetros de consulta são analisados automaticamente nos argumentos correspondentes da função
  • O corpo da solicitação POST fica disponível por meio de jsonlite::fromJSON(req$postBody)
  • Defina res$status para respostas HTTP diferentes de 200
  • Retorne listas nomeadas — elas são serializadas automaticamente como objetos JSON

Perguntas Frequentes

A aula “Criando endpoints GET e POST” é grátis?

Sim — o texto completo de “Criando endpoints GET e POST” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de R Academy, atualize para CoddyKit PRO. O curso de R Academy inclui 4 aulas no total.

O que vou aprender em “Criando endpoints GET e POST”?

Lide com parâmetros de caminho, strings de consulta e análise do corpo das solicitações. Você pratica R Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar R Academy?

Nenhuma experiência prévia é necessária. R Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Criando endpoints GET e POST”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de R Academy?

Sim. Cada aula de R Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Introdução ao Plumber e REST
  2. Criando endpoints GET e POST
  3. Autenticação e segurança de APIs
  4. Implantando APIs Plumber em produção
← Voltar para R Academy