R Academy · Lektion

Introduktion till Plumber och REST

Förstå REST-principer och annotera R-funktioner som API-endpoints.

Lektion 1 av 413 steg

Introduktion till Plumber och REST är en gratis lektion i R Academy på CoddyKit. Detta är lektion 1 av 4. Du kan läsa vilka 3 lektioner som helst i den här lärvägen kostnadsfritt i sin helhet – därefter låser CoddyKit PRO upp alla lektioner, plus praktisk övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Den ingår i lärvägen för R Academy, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i R Academy innehåller totalt 4 lektioner.

Vad är ett REST-API?

Ett REST-API (Representational State Transfer) är en webbtjänst som exponerar data och funktioner via HTTP. Viktiga principer:

Statslöst: varje begäran innehåller all information som behövs; ingen serversidesession används.
Resursorienterat: endpoints representerar resurser (/users, /predictions).
HTTP:s standardverb: GET (läsa), POST (skapa), PUT (uppdatera), DELETE (ta bort).
JSON: standardformatet för data i begärande- och svarsmeddelanden.

# 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')

Syntax för plumber-annotationer

plumber använder särskilda kommentarannotationer som börjar med #* för att definiera API-endpoints. Placera en annotation direkt ovanför den R-funktion som hanterar endpointen. Funktionens argument motsvarar parametrar i begäran; returvärdet blir JSON-innehållet i svaret.

# 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() – skapa en Plumber-router

pr('plumber.R') läser en plumber-fil och skapar ett routerobjekt som registrerar alla annoterade endpoints. Routern är det centrala objekt som konfigureras (med filter, serialiserare med mera) innan servern startas.

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() – starta servern

pr_run(router, host, port) startar plumber-API-servern. Som standard binder den till 127.0.0.1:8000. Ange host = '0.0.0.0' för att acceptera anslutningar från alla nätverksgränssnitt (vilket krävs för Docker eller fjärråtkomst).

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__/')

@get-annotation

Annotationen #* @get /path kopplar en GET-begäran till funktionen. Parametrar i frågesträngen (till exempel ?name=Alice) skickas automatiskt som argument till R-funktionen. Om ingen konverteringsannotation anges tas parametrarna emot som teckensträngar.

# 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"}

@post-annotation

Annotationen #* @post /path kopplar en POST-begäran till funktionen. Begärans innehåll (vanligen JSON) är åtkomligt via specialargumentet req som req$body (en tolkad lista när begärans innehåll är JSON). POST används för operationer som skapar resurser eller utlöser beräkningar.

# 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)
  )
}

JSON-serialiserare

Som standard serialiserar plumber returvärden till JSON med hjälp av jsonlite. Annotationen #* @serializer json gör detta uttryckligt. Du kan konfigurera serialiseringsalternativ, till exempel pretty-printing eller hantering av null-värden, genom att ange dem som en JSON-lista i annotationen.

# 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]}

HTTP-verb – PUT, DELETE, PATCH

plumber stöder alla vanliga HTTP-verb via motsvarande annotationer:

#* @put /path: fullständig ersättning av en resurs.
#* @delete /path: tar bort en resurs.
#* @patch /path: utför en partiell uppdatering av en resurs.
#* @head /path: endast headers (inget innehåll).

# 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)
}

Sökvägsparametrar

Sökvägsparametrar definieras med vinkelparenteser i routen: /user/. plumber hämtar värdet från URL:en och skickar det som ett funktionsargument med samma namn. Dessa skiljer sig från frågeparametrar, som visas efter ?.

# 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)
  )
}

Felhantering

När en R-funktion genererar ett fel fångar plumber det och returnerar ett HTTP-svar med status 500, där felmeddelandet finns i JSON. För API:er som riktar sig till användare bör du uttryckligen returnera lämpliga HTTP-statuskoder med hjälp av res$status och stop() för valideringsfel.

# 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)
}

Automatiskt genererad Swagger-dokumentation

plumber genererar automatiskt interaktiv Swagger UI-dokumentation från dina annotationer. Besök /__docs__/ när servern körs för att se alla endpoints och deras parametrar samt prova dem i webbläsaren. Använd #* @tag för att gruppera endpoints på ett logiskt sätt.

# 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))
}

Snabbkontroll

I plumber, vad är skillnaden mellan en frågeparameter (till exempel /greet?name=Alice) och en sökvägsparameter (till exempel /user/42)?

Besvara frågan i den interaktiva lektionen

Sammanfattning av plumber och REST

Viktiga punkter från Introduktion till plumber och REST:

REST är statslöst, resursorienterat, använder HTTP:s standardverb och returnerar JSON.
plumber kopplar R-funktioner till endpoints med #*-annotationer ovanför funktionerna.
pr('file.R') skapar en router; pr_run(api, host, port) startar servern.
#* @get /path hanterar GET; #* @post /path hanterar POST.
Sökvägsparametrar: /user/; frågeparametrar: /search?term=foo.
Returnera namngivna listor – plumber serialiserar dem automatiskt till JSON.
Swagger UI genereras automatiskt på /__docs__/ från dina annotationer.

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

Gratis att börja

Lär dig R med en AI-lärare – gratis

Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.

Kurser: 43
Lektioner: 159

Börja lära dig gratis Visa hela kursen

Vanliga frågor

Är lektionen ”Introduktion till Plumber och REST” gratis?

Ja – du kan läsa vilka 3 lektioner som helst i lärvägen R Academy, inklusive ”Introduktion till Plumber och REST”, kostnadsfritt i sin helhet här på webben. Därefter låser CoddyKit PRO upp alla lektioner, plus interaktiv övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Kursen i R Academy innehåller totalt 4 lektioner.

Vad lär jag mig i ”Introduktion till Plumber och REST”?

Förstå REST-principer och annotera R-funktioner som API-endpoints. Ni övar på R Academy med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.

Behöver jag någon erfarenhet för att börja lära mig R Academy?

Du behöver inga förkunskaper. Utbildningen i R Academy på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 1 av 4.

Hur lång tid tar lektionen ”Introduktion till Plumber och REST”?

De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.

Kan jag skriva och köra kod i den här R Academy-lektionen?

Ja. Varje R Academy-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.

Alla lektioner i den här kursen

← Tillbaka till R Academy