R Academy · Lezione

Creazione di endpoint GET e POST

Gestisca i parametri del percorso, le stringhe di query e l'analisi del corpo delle richieste

Lezione 2 di 413 passaggi

Creazione di endpoint GET e POST è una lezione R Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento R Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso R Academy include 4 lezioni in totale.

Che cos'è Plumber?

plumber trasforma le normali funzioni R in endpoint di API HTTP utilizzando annotazioni speciali nei commenti. Annoti una funzione con #* @get /path e Plumber crea una route GET che chiama quella funzione e restituisce il risultato in formato JSON.

Installi il package con install.packages('plumber').

Il primo endpoint GET

Un'API Plumber di base risiede in un file, ad esempio api.R. Annoti la funzione con #* @get seguito dal percorso. Plumber serializza automaticamente in JSON il valore restituito dalla funzione.

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

Parametri del percorso con indicazioni sul tipo

Inserisca segmenti variabili nel percorso utilizzando la sintassi con parentesi angolari: /users/<id:int>. Plumber analizza il segmento e lo passa alla funzione come argomento del tipo appropriato. I tipi supportati includono 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"}

Parametri della query con #* @param

Documenti i parametri della query con #* @param name Description. Il nome del parametro deve corrispondere al nome dell'argomento della funzione. Plumber lo legge automaticamente dalla query string: non è necessario analizzarlo manualmente.

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

Creazione di un endpoint POST

Utilizzi #* @post /path per gli endpoint che ricevono un corpo della richiesta. L'argomento speciale req consente di accedere all'oggetto della richiesta non elaborato. Plumber lo passa automaticamente quando l'argomento della funzione si chiama 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
#   )
# }

Analisi del corpo della richiesta

req$postBody contiene la stringa JSON non elaborata proveniente dal corpo della richiesta POST. La analizzi con jsonlite::fromJSON(req$postBody) per ottenere una lista R con nomi. Convalidi sempre i campi obbligatori prima dell'elaborazione.

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

Codici di stato HTTP con res$status

L'argomento res, inserito automaticamente anche da Plumber, consente di impostare il codice di stato della risposta HTTP. Lo imposti prima di restituire il risultato: res$status <- 404L. Codici comuni:

200 — OK (predefinito)
201 — Creato
400 — Richiesta non valida
404 — Non trovato
500 — Errore interno del server

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

Restituzione di liste con nomi come JSON

Plumber serializza i valori restituiti da R in JSON utilizzando jsonlite. Le liste con nomi diventano oggetti JSON, mentre le liste senza nomi diventano array JSON. Restituisca una lista con nomi per ottenere risposte strutturate.

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

L'oggetto router di Plumber

Carichi un file R annotato con plumb('api.R') per creare un oggetto router Plumber. Chiami pr$run(port = 8000) per avviare il server. In produzione, in genere si chiama 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

Gestire più metodi HTTP

Un singolo percorso può supportare più metodi definendo funzioni annotate separate. Plumber indirizza le richieste alla funzione corretta in base al metodo HTTP utilizzato.

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

Testare gli endpoint dell'API

Utilizzi curl dal terminale o httr2 da R per testare gli endpoint mentre il server è in esecuzione. httr2 consente di scrivere test riproducibili insieme al codice dell'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 rapida: parametri del percorso

Come si dichiara un parametro del percorso denominato id che Plumber deve analizzare come numero intero?

Rispondi nella lezione interattiva

Riepilogo degli endpoint GET e POST

Creazione di endpoint REST con Plumber:

#* @get /path crea una route GET; #* @post /path crea una route POST
I parametri del percorso utilizzano la sintassi <name:type> (int, dbl, chr)
I parametri della query vengono analizzati automaticamente e assegnati agli argomenti della funzione corrispondenti
Il corpo delle richieste POST è disponibile tramite jsonlite::fromJSON(req$postBody)
Imposti res$status per le risposte HTTP diverse da 200
Restituisca liste con nomi: vengono serializzate automaticamente come oggetti JSON

Gratis per iniziare

Impara R con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 43
Lezioni: 159

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Creazione di endpoint GET e POST» è gratuita?

Sì — il testo completo di «Creazione di endpoint GET e POST» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso R Academy, passa a CoddyKit PRO. Il corso R Academy include 4 lezioni in totale.

Cosa imparerò in «Creazione di endpoint GET e POST»?

Gestisca i parametri del percorso, le stringhe di query e l'analisi del corpo delle richieste Eserciti R Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare R Academy?

Non è richiesta alcuna esperienza precedente. R Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Creazione di endpoint GET e POST»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione R Academy?

Sì. Ogni lezione R Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Introduzione a Plumber e REST
Creazione di endpoint GET e POST
Autenticazione e sicurezza delle API
Distribuzione in produzione delle API Plumber

← Torna a R Academy