R Academy · Leçon

Créer des points d’accès GET et POST

Gérez les paramètres de chemin, les chaînes de requête et l’analyse du corps des requêtes.

Leçon 2 sur 413 étapes

Créer des points d’accès GET et POST est une leçon R Academy gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage R Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours R Academy comprend 4 leçons au total.

Qu’est-ce que Plumber ?

plumber transforme des fonctions R ordinaires en points de terminaison d’API HTTP grâce à des annotations spéciales sous forme de commentaires. Annotez une fonction avec #* @get /path et Plumber crée une route GET qui appelle cette fonction et renvoie son résultat au format JSON.

Installez-le avec install.packages('plumber').

Votre premier point de terminaison GET

Une API Plumber de base se trouve dans un fichier (par exemple api.R). Annotez la fonction avec #* @get suivi du chemin. Plumber sérialise automatiquement la valeur renvoyée par la fonction au format 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)

Paramètres de chemin avec indication de type

Insérez des segments de chemin variables à l’aide de la syntaxe entre chevrons : /users/<id:int>. Plumber analyse le segment et le transmet comme argument typé à votre fonction. Les types pris en charge comprennent int, dbl et 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"}

Paramètres de requête avec #* @param

Documentez les paramètres de requête avec #* @param name Description. Le nom du paramètre doit correspondre au nom de l’argument de la fonction. Plumber le lit automatiquement dans la chaîne de requête : aucune analyse manuelle n’est nécessaire.

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

Créer un point de terminaison POST

Utilisez #* @post /path pour les points de terminaison qui reçoivent un corps de requête. L’argument spécial req donne accès à l’objet de requête brut. Plumber le transmet automatiquement lorsque l’argument de la fonction s’appelle 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
#   )
# }

Analyser le corps de la requête

req$postBody contient la chaîne JSON brute du corps POST. Analysez-la avec jsonlite::fromJSON(req$postBody) pour obtenir une liste R nommée. Validez toujours les champs obligatoires avant le traitement.

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

Codes d’état HTTP avec res$status

L’argument res (également injecté automatiquement par Plumber) vous permet de définir le code d’état de la réponse HTTP. Définissez-le avant de renvoyer la réponse : res$status <- 404L. Codes courants :

200 — OK (par défaut)
201 — Créé
400 — Requête incorrecte
404 — Introuvable
500 — Erreur interne du serveur

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

Renvoyer des listes nommées au format JSON

Plumber sérialise les valeurs R renvoyées au format JSON à l’aide de jsonlite. Les listes nommées deviennent des objets JSON ; les listes non nommées deviennent des tableaux JSON. Renvoyez une liste nommée pour les réponses structurées.

# 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’objet routeur de Plumber

Chargez un fichier R annoté avec plumb('api.R') pour créer un objet router Plumber. Appelez pr$run(port = 8000) pour démarrer le serveur. En production, vous appelez généralement 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

Gérer plusieurs méthodes HTTP

Un même chemin peut prendre en charge plusieurs méthodes en écrivant des fonctions annotées distinctes. Plumber achemine les requêtes vers la fonction appropriée selon la méthode HTTP utilisée.

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

Tester les points de terminaison de votre API

Utilisez curl depuis le terminal ou httr2 depuis R pour tester les points de terminaison pendant que le serveur fonctionne. httr2 vous permet d’écrire des tests reproductibles à côté du code de votre 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)

Vérification rapide : paramètres de chemin

Comment déclarer un paramètre de chemin nommé id que Plumber doit analyser comme un entier ?

Réponds-y dans la leçon interactive

Récapitulatif des points de terminaison GET et POST

Créer des points de terminaison REST avec Plumber :

#* @get /path crée une route GET ; #* @post /path crée une route POST
Les paramètres de chemin utilisent la syntaxe <name:type> (int, dbl, chr)
Les paramètres de requête sont automatiquement analysés et transmis aux arguments correspondants de la fonction
Le corps d’une requête POST est accessible via jsonlite::fromJSON(req$postBody)
Définissez res$status pour les réponses HTTP autres que 200
Retournez des listes nommées : elles sont automatiquement sérialisées en objets JSON

Gratuit pour commencer

Apprends R avec un tuteur IA — gratuit

Écris et exécute du vrai code dans ton navigateur, obtiens de l'aide instantanée d'un tuteur IA disponible 24h/24, et reprends là où tu t'es arrêté sur le web ou dans l'app.

Cours: 43
Leçons: 159

Commencer gratuitement Voir le cours complet

Questions Fréquemment Posées

La leçon « Créer des points d’accès GET et POST » est-elle gratuite ?

Oui — le texte complet de « Créer des points d’accès GET et POST » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours R Academy, passe à CoddyKit PRO. Le cours R Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Créer des points d’accès GET et POST » ?

Gérez les paramètres de chemin, les chaînes de requête et l’analyse du corps des requêtes. Tu pratiques R Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer R Academy ?

Aucune expérience préalable n'est requise. R Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Créer des points d’accès GET et POST » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon R Academy ?

Oui. Chaque leçon R Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à R Academy