R Academy · Aula

Introdução ao Plumber e REST

Entenda os princípios REST e anote funções do R como endpoints de API.

Introdução ao Plumber e REST é uma aula grátis de R Academy no CoddyKit. Esta é a aula 1 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 é uma API REST?

Uma API REST (Transferência de Estado Representacional) é um serviço Web que expõe dados e operações por meio de HTTP. Princípios fundamentais:

Sem estado: cada solicitação contém todas as informações necessárias; não há sessão no servidor.
Orientada a recursos: os pontos de acesso representam recursos (/users, /predictions).
Verbos HTTP padrão: GET (ler), POST (criar), PUT (atualizar), DELETE (remover).
JSON: o formato de dados padrão para os corpos das solicitações e respostas.

# REST API concepts in HTTP terms:
# GET /api/model/predict?x=5      -> read a prediction
# POST /api/model/train           -> create a new model
# GET /api/data/summary           -> read data summary
# DELETE /api/cache/flush         -> remove cached results

# Plumber maps R functions to these HTTP endpoints
cat('REST: stateless, resource-oriented, JSON responses')

Sintaxe de anotações do plumber

O plumber usa anotações especiais em comentários que começam com #* para definir pontos de acesso da API. Coloque uma anotação diretamente acima da função R que gerencia o ponto de acesso. Os argumentos da função correspondem aos parâmetros da solicitação; o valor retornado se torna o corpo da resposta JSON.

# plumber.R
library(plumber)

#* @get /ping
function() {
  list(status = 'ok', time = Sys.time())
}

#* @get /add
#* @param a:int First number
#* @param b:int Second number
function(a, b) {
  list(result = as.integer(a) + as.integer(b))
}

pr() — criando um roteador Plumber

pr('plumber.R') lê um arquivo do plumber e cria um objeto roteador que registra todos os pontos de acesso anotados. O roteador é o objeto central que você configura (adicionando filtros, serializadores etc.) antes de executá-lo.

library(plumber)

# Create a router from a plumber file
api <- pr('plumber.R')

# Inspect registered routes
print(api$routes)

# Alternatively, define inline without a file:
api <- pr() |>
  pr_get('/ping', function() list(status = 'ok')) |>
  pr_post('/echo', function(req) req$body)

pr_run() — iniciando o servidor

pr_run(router, host, port) inicia o servidor da API plumber. Por padrão, ele se vincula a 127.0.0.1:8000. Defina host = '0.0.0.0' para aceitar conexões de qualquer interface de rede (necessário para Docker ou acesso remoto).

library(plumber)

api <- pr('plumber.R')

# Start server on localhost port 8000
# pr_run(api, host = '127.0.0.1', port = 8000)

# For Docker/remote access, bind to all interfaces
# pr_run(api, host = '0.0.0.0', port = 8000)

# View auto-generated Swagger docs in browser
# (automatically available at /docs or /__docs__/ endpoint)
cat('Swagger UI auto-generated at http://localhost:8000/__docs__/')

Anotação @get

A anotação #* @get /path associa uma solicitação GET à função. Os parâmetros da cadeia de consulta (por exemplo, ?name=Alice) são passados automaticamente como argumentos da função R. Se nenhuma anotação de conversão for fornecida, os parâmetros serão recebidos como cadeias de caracteres.

# plumber.R

#* Greet a user by name
#* @param name:str The name to greet
#* @get /greet
function(name = 'World') {
  list(
    message = paste('Hello,', name),
    timestamp = format(Sys.time(), '%Y-%m-%d %H:%M:%S')
  )
}
# GET /greet?name=Alice
# -> {"message":"Hello, Alice","timestamp":"2026-01-01 12:00:00"}

Anotação @post

A anotação #* @post /path associa uma solicitação POST à função. O corpo da solicitação (normalmente em JSON) pode ser acessado pelo argumento especial req como req$body (uma lista analisada quando o corpo da solicitação está em JSON). POST é usado para operações que criam recursos ou iniciam cálculos.

# plumber.R

#* Run a linear model prediction
#* @post /predict
function(req) {
  # req$body is already parsed from JSON
  input_data <- as.data.frame(req$body)

  # Run prediction with a pre-loaded model
  predictions <- predict(trained_model, newdata = input_data)

  list(
    predictions = as.numeric(predictions),
    n           = nrow(input_data)
  )
}

Serializador JSON

Por padrão, o plumber serializa os valores retornados para JSON usando jsonlite. A anotação #* @serializer json torna isso explícito. Você pode configurar opções do serializador, como formatação ou tratamento de valores nulos, especificando-as como uma lista JSON na anotação.

# Default: automatic JSON serialization
#* @get /data
function() {
  list(values = 1:5, labels = c('a', 'b', 'c', 'd', 'e'))
}

# Explicit JSON serializer with options
#* @serializer json list(na = 'null', auto_unbox = TRUE)
#* @get /data_explicit
function() {
  list(value = 42, missing = NA)
}
# With auto_unbox=TRUE: {"value":42} not {"value":[42]}

Verbos HTTP — PUT, DELETE, PATCH

O plumber oferece suporte a todos os verbos HTTP padrão por meio de anotações correspondentes:

#* @put /path: substituição completa de um recurso.
#* @delete /path: remoção de um recurso.
#* @patch /path: atualização parcial de um recurso.
#* @head /path: somente cabeçalhos (sem corpo).

# plumber.R — CRUD-style endpoints

#* Update a model configuration
#* @put /config/<model_id>
function(model_id, req) {
  config <- req$body
  save_config(model_id, config)
  list(updated = model_id, config = config)
}

#* Remove cached results
#* @delete /cache/<key>
function(key) {
  cache_env <- globalenv()$cache
  rm(list = key, envir = cache_env)
  list(deleted = key)
}

Parâmetros de caminho

Os parâmetros de caminho são definidos usando sinais de menor e maior na rota: /user/. O plumber extrai o valor da URL e o passa como um argumento da função com o mesmo nome. Eles são diferentes dos parâmetros de consulta (que aparecem depois de ?).

# plumber.R

#* Get stats for a specific dataset
#* @param dataset_id:str The dataset identifier
#* @get /datasets/<dataset_id>/stats
function(dataset_id) {
  if (!dataset_id %in% available_datasets()) {
    stop(paste('Dataset not found:', dataset_id))
  }
  ds <- load_dataset(dataset_id)
  list(
    id    = dataset_id,
    rows  = nrow(ds),
    cols  = ncol(ds),
    names = names(ds)
  )
}

Tratamento de erros

Quando uma função R gera um erro, o plumber o captura e retorna uma resposta HTTP 500 com a mensagem de erro em JSON. Em APIs voltadas para usuários, retorne explicitamente códigos de status HTTP apropriados usando res$status e stop() para erros de validação.

# plumber.R

#* Divide two numbers safely
#* @get /divide
function(a, b, res) {
  a <- suppressWarnings(as.numeric(a))
  b <- suppressWarnings(as.numeric(b))

  if (is.na(a) || is.na(b)) {
    res$status <- 400  # Bad Request
    return(list(error = 'Both a and b must be numeric'))
  }
  if (b == 0) {
    res$status <- 422  # Unprocessable Entity
    return(list(error = 'Division by zero is not allowed'))
  }
  list(result = a / b)
}

Documentação Swagger gerada automaticamente

O plumber gera automaticamente uma documentação interativa da interface do Swagger a partir das suas anotações. Acesse /__docs__/ quando o servidor estiver em execução para ver todos os pontos de acesso e seus parâmetros e testá-los no navegador. Use #* @tag para agrupar logicamente os pontos de acesso.

# plumber.R with Swagger metadata

#* @apiTitle My ML Prediction API
#* @apiDescription Serves predictions from trained R models
#* @apiVersion 1.0.0

#* @tag model
#* @get /health
function() list(status = 'healthy')

#* Predict house price
#* @tag prediction
#* @param sqft:dbl Square footage
#* @param bedrooms:int Number of bedrooms
#* @get /predict
function(sqft = 1000, bedrooms = 3) {
  pred <- predict(price_model, data.frame(sqft = as.numeric(sqft),
                                          bedrooms = as.integer(bedrooms)))
  list(predicted_price = round(as.numeric(pred), 2))
}

Verificação rápida

No plumber, qual é a diferença entre um parâmetro de consulta (por exemplo, /greet?name=Alice) e um parâmetro de caminho (por exemplo, /user/42)?

Recapitulação de plumber e REST

Principais aprendizados da introdução ao plumber e ao REST:

REST: sem estado, orientado a recursos, usa verbos HTTP padrão e retorna JSON.
O plumber associa funções R a pontos de acesso usando anotações #* acima das funções.
pr('file.R') cria um roteador; pr_run(api, host, port) inicia o servidor.
#* @get /path gerencia GET; #* @post /path gerencia POST.
Parâmetros de caminho: /user/; parâmetros de consulta: /search?term=foo.
Retorne listas nomeadas — o plumber as serializa automaticamente para JSON.
A interface do Swagger é gerada automaticamente em /__docs__/ a partir das suas anotações.

# Complete minimal plumber API
library(plumber)

#* @apiTitle Simple Prediction API

#* Health check
#* @get /health
function() list(status = 'ok')

#* Predict mpg from weight
#* @param wt:dbl Car weight (1000 lbs)
#* @get /predict
function(wt = 3.0) {
  pred <- predict(lm(mpg ~ wt, data = mtcars),
                  newdata = data.frame(wt = as.numeric(wt)))
  list(wt = as.numeric(wt), predicted_mpg = round(pred, 2))
}

# Run:
# api <- pr('plumber.R')
# pr_run(api, port = 8000)

Perguntas Frequentes

A aula “Introdução ao Plumber e REST” é grátis?

Sim — o texto completo de “Introdução ao Plumber e REST” é 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 “Introdução ao Plumber e REST”?

Entenda os princípios REST e anote funções do R como endpoints de API. 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 1 de 4.

Quanto tempo leva a aula “Introdução ao Plumber e REST”?

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

← Voltar para R Academy