Creación de endpoints GET y POST
Gestione parámetros de ruta, cadenas de consulta y el análisis del cuerpo de las solicitudes.
Creación de endpoints GET y POST es una lección gratuita de R Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de R Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de R Academy incluye 4 lecciones en total.
¿Qué es Plumber?
plumber convierte funciones de R ordinarias en endpoints de API HTTP mediante anotaciones especiales en comentarios. Anote una función con #* @get /path y Plumber crea una ruta GET que llama a esa función y devuelve su resultado en formato JSON.
Instálelo con install.packages('plumber').
Su primer endpoint GET
Una API básica de Plumber se encuentra en un archivo (por ejemplo, api.R). Anote la función con #* @get seguido de la ruta. Plumber serializa automáticamente a JSON el valor devuelto por la función.
# 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 ruta con indicaciones de tipo
Inserte segmentos de ruta variables mediante la sintaxis de corchetes angulares: /users/<id:int>. Plumber analiza el segmento y lo pasa como argumento tipado a su función. Los tipos admitidos incluyen int, dbl y 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 con #* @param
Documente los parámetros de consulta con #* @param name Description. El nombre del parámetro debe coincidir con el nombre del argumento de la función. Plumber lo lee automáticamente de la cadena de consulta; no es necesario analizarla 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)
# }Creación de un endpoint POST
Use #* @post /path para los endpoints que reciben un cuerpo de solicitud. El argumento especial req proporciona acceso al objeto de solicitud sin procesar. Plumber lo pasa automáticamente cuando el argumento de la función se llama 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
# )
# }Análisis del cuerpo de la solicitud
req$postBody contiene la cadena JSON sin procesar del cuerpo POST. Analícela con jsonlite::fromJSON(req$postBody) para obtener una lista de R con nombres. Valide siempre los campos obligatorios antes de procesarlos.
# #* @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 estado HTTP con res$status
El argumento res (que Plumber también inyecta automáticamente) permite establecer el código de estado de la respuesta HTTP. Establézcalo antes de devolver el resultado: res$status <- 404L. Códigos habituales:
- 200 — Correcto (predeterminado)
- 201 — Creado
- 400 — Solicitud incorrecta
- 404 — No encontrado
- 500 — Error interno del 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]]
# }Devolución de listas con nombres como JSON
Plumber serializa los valores devueltos por R a JSON mediante jsonlite. Las listas con nombres se convierten en objetos JSON; las listas sin nombres, en matrices JSON. Devuelva una lista con nombres para obtener respuestas estructuradas.
# 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}]}El objeto router de Plumber
Cargue un archivo R anotado con plumb('api.R') para crear un objeto router de Plumber. Llame a pr$run(port = 8000) para iniciar el servidor. En producción, normalmente se llama a 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/helloGestión de varios métodos HTTP
Una misma ruta puede admitir varios métodos mediante funciones anotadas independientes. Plumber dirige las solicitudes a la función correcta según el método HTTP utilizado.
# #* 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)
# }Prueba de los endpoints de su API
Use curl desde la terminal o httr2 desde R para probar los endpoints mientras el servidor está en ejecución. httr2 permite escribir pruebas reproducibles junto con el código de su 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)Comprobación rápida: parámetros de ruta
¿Cómo se declara un parámetro de ruta llamado id que Plumber debe analizar como un entero?
Repaso de los endpoints GET y POST
Creación de endpoints REST con Plumber:
#* @get /pathcrea una ruta GET;#* @post /pathcrea una ruta POST- Los parámetros de ruta usan la sintaxis
<name:type>(int,dbl,chr) - Los parámetros de consulta se analizan automáticamente y se asignan a los argumentos correspondientes de la función
- El cuerpo de una solicitud POST está disponible mediante
jsonlite::fromJSON(req$postBody) - Establezca
res$statuspara las respuestas HTTP que no sean 200 - Devuelva listas con nombres: se serializan automáticamente como objetos JSON
Preguntas frecuentes
¿La lección «Creación de endpoints GET y POST» es gratis?
Sí — el texto completo de «Creación de endpoints GET y POST» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de R Academy, actualiza a CoddyKit PRO. El curso de R Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Creación de endpoints GET y POST»?
Gestione parámetros de ruta, cadenas de consulta y el análisis del cuerpo de las solicitudes. Practicas R Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar R Academy?
No se requiere experiencia previa. R Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.
¿Cuánto tiempo toma la lección «Creación de endpoints GET y POST»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de R Academy?
Sí. Cada lección de R Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Introducción a Plumber y REST
- Creación de endpoints GET y POST
- Autenticación y seguridad de API
- Implementación de API de Plumber en producción