R Academy · 강의

Plumber와 REST 입문

REST 원칙을 이해하고 R 함수를 API 엔드포인트로 주석 처리합니다.

Plumber와 REST 입문은(는) CoddyKit의 무료 R Academy 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 R Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. R Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

REST API란 무엇입니까

REST(Representational State Transfer) API는 HTTP를 통해 데이터와 작업을 제공하는 웹 서비스입니다. 주요 원칙은 다음과 같습니다:

무상태: 각 요청에 필요한 모든 정보가 포함되며 서버 측 세션은 사용하지 않습니다.
리소스 중심: 엔드포인트가 리소스를 나타냅니다(/users, /predictions).
표준 HTTP 동사: GET(읽기), POST(생성), PUT(업데이트), DELETE(삭제).
JSON: 요청 본문과 응답 본문에 사용하는 표준 데이터 형식입니다.

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

plumber 주석 구문

plumber는 #*로 시작하는 특수 주석을 사용하여 API 엔드포인트를 정의합니다. 엔드포인트를 처리하는 R 함수 바로 위에 주석을 작성하십시오. 함수 인수는 요청 매개변수에 매핑되고, 반환값은 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() — Plumber 라우터 만들기

pr('plumber.R')은 plumber 파일을 읽고 주석이 달린 모든 엔드포인트를 등록하는 라우터 객체를 만듭니다. 라우터는 실행하기 전에 구성하는 중심 객체입니다(필터, 직렬화기 등을 추가할 수 있습니다).

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() — 서버 시작

pr_run(router, host, port)는 plumber API 서버를 시작합니다. 기본적으로 127.0.0.1:8000에 바인딩됩니다. 모든 네트워크 인터페이스의 연결을 허용하려면 host = '0.0.0.0'으로 설정하십시오(Docker 또는 원격 접근에 필요합니다).

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 주석

#* @get /path 주석은 GET 요청을 함수에 매핑합니다. 쿼리 문자열 매개변수(예: ?name=Alice)는 R 함수 인수로 자동 전달됩니다. 변환 주석을 지정하지 않으면 매개변수는 문자형 문자열로 전달됩니다.

# 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 주석

#* @post /path 주석은 POST 요청을 함수에 매핑합니다. 요청 본문(일반적으로 JSON)은 특수 req 인수를 통해 req$body로 접근할 수 있습니다(요청 본문이 JSON이면 파싱된 목록으로 제공됩니다). POST는 리소스를 생성하거나 계산을 시작하는 작업에 사용합니다.

# 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 직렬화기

기본적으로 plumber는 jsonlite를 사용하여 반환값을 JSON으로 직렬화합니다. #* @serializer json 주석을 사용하면 이 동작을 명시적으로 지정할 수 있습니다. 주석에 JSON 목록으로 지정하여 보기 좋게 출력하거나 null을 처리하는 등의 직렬화기 옵션을 구성할 수 있습니다.

# 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 동사 — PUT, DELETE, PATCH

plumber는 일치하는 주석을 통해 모든 표준 HTTP 동사를 지원합니다:

#* @put /path: 리소스를 전체 교체합니다.
#* @delete /path: 리소스를 삭제합니다.
#* @patch /path: 리소스를 부분적으로 업데이트합니다.
#* @head /path: 헤더만 반환합니다(본문 없음).

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

경로 매개변수

경로 매개변수는 라우트에서 꺾쇠괄호를 사용하여 정의합니다: /user/. plumber는 URL에서 값을 추출하여 같은 이름의 함수 인수로 전달합니다. 이는 쿼리 매개변수(? 뒤에 표시됨)와 다릅니다.

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

오류 처리

R 함수에서 오류가 발생하면 plumber가 이를 포착하고 오류 메시지를 JSON으로 담은 500 HTTP 응답을 반환합니다. 사용자에게 제공되는 API에서는 res$status와 stop()을 사용하여 유효성 검사 오류에 적절한 HTTP 상태 코드를 명시적으로 반환하십시오.

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

자동 생성되는 Swagger 문서

plumber는 주석에서 대화형 Swagger UI 문서를 자동으로 생성합니다. 서버가 실행 중일 때 /__docs__/를 방문하면 모든 엔드포인트와 해당 매개변수를 확인하고 브라우저에서 직접 테스트할 수 있습니다. 엔드포인트를 논리적으로 그룹화하려면 #* @tag를 사용하십시오.

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

빠른 확인

plumber에서 쿼리 매개변수(예: /greet?name=Alice)와 경로 매개변수(예: /user/42)는 어떻게 다릅니까?

plumber와 REST 복습

plumber와 REST 입문의 핵심 내용:

REST는 무상태이고 리소스 중심이며 표준 HTTP 동사를 사용하고 JSON을 반환합니다.
plumber는 함수 위에 #* 주석을 작성하여 R 함수를 엔드포인트에 매핑합니다.
pr('file.R')은 라우터를 만들고, pr_run(api, host, port)는 서버를 시작합니다.
#* @get /path는 GET을 처리하고, #* @post /path는 POST를 처리합니다.
경로 매개변수: /user/; 쿼리 매개변수: /search?term=foo.
이름이 지정된 목록을 반환하면 plumber가 자동으로 JSON으로 직렬화합니다.
주석에서 Swagger UI가 /__docs__/에 자동으로 생성됩니다.

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

자주 묻는 질문

“Plumber와 REST 입문” 강의는 무료인가요?

네 — “Plumber와 REST 입문” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 R Academy 강의 전체를 잠금 해제할 수 있습니다. R Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“Plumber와 REST 입문”에서 뭘 배우나요?

REST 원칙을 이해하고 R 함수를 API 엔드포인트로 주석 처리합니다. 브라우저에서 직접 실행하는 실습 코드로 R Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

R Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 R Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.

“Plumber와 REST 입문” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 R Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 R Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← R Academy(으)로 돌아가기