Ako vytvoriť API v R pomocou knižnice Plumber

Endpointy

Endpointy sú špeciálne funkcie, ktoré definujú ako bude API reagovať na rôzne HTTP požiadavky. Napríklad, ak chcete vytvoriť endpoint pre GET požiadavku, môžete použiť #* @get /názov. Pre POST požiadavku použijete #* @post /názov. Viac informácií o HTTP metódach nájdete na restapitutorial.

Serializácia

Plumber podporuje rôzne formáty serializácie, ako sú JSON, CSV, HTML a ďalšie. Defaultne je nastavený JSON, ale môžete si zvoliť iný formát pomocou #* @serializer. Napríklad, ak chcete vrátiť odpoveď vo formáte CSV, môžete použiť #* @serializer csv. Medzi ďalšie formáty patria napr. parquet, html, pdf, jpeg, png a iné.

Programové volanie

Okrem tvorby API pomocou anotácií môžete vytvoriť API aj programovo. Na to slúži funkcia pr() (plumber router), ktorá vám umožňuje definovať API pomocou R6 objektov. Tento prístup je užitočný, ak potrebujete väčšiu flexibilitu a kontrolu.

Ďalšie info

Pre viac informácií o tvorbe API pomocou knižnice Plumber odporúčam navštíviť oficiálnu stránku. V sekcii “Articles” nájdete množstvo užitočných článkov a príkladov, ktoré vám pomôžu lepšie pochopiť, ako Plumber funguje. Okrem základných návodov tam nájdete aj články venujúce sa bezpečnosti, hostingu a nasadeniu API do produkcie.

Štruktúra projektu

Naša ukážková aplikácia umožňuje predikovať cenu bytu podľa rôznych parametrov, ako je lokalita, rozloha, stav či typ bytu. je to rovnaký model ako sme použili v tomto blogu a Shiny aplikácii. Upozorňujem, že model bol trénovaný na dátach z konca roka 2023 a jeho predikcie sú len orientačné.

Štruktúra nášho projektu vyzerá nasledovne:

.
├── app.R
├── data
│   ├── bundled.RDS
│   ├── certificates.RDS
│   ├── conditions.RDS
│   ├── districts.RDS
│   ├── districts_mapping.RDS
│   ├── index.RDS
│   ├── latlon.RDS
│   ├── municipalities.RDS
│   └── types.RDS
├── docker-compose.yaml
├── Dockerfile
├── helpers
│   ├── logging.R
│   └── validator.R
└── logs
    ├── plumber_20250420_185501.log
    └── plumber_20250421_094015.log

V hlavnom skripte app.R načítavame model aj potrebné dáta (obe z priečinku data na diagrame), definujeme API endpointy a spúšťame samotné API. Na spracovanie vstupov využívame pomocné skripty.
Skript validator.R obsahuje funkcie na validáciu vstupných parametrov, ktoré sú volané v rámci API endpointov. Skript error.R obsahuje funkcie na spracovanie chýb a logovanie.R obsahuje funkcie na logovanie požiadaviek a odpovedí.
Skript logging.R obsahuje funkcie na logovanie požiadaviek a odpovedí. Tieto funkcie sú volané v rámci API endpointov a slúžia na sledovanie správania API a identifikáciu chýb. Na diagrame vidíme príklady .log súborov pod priečinkom “logs”, ktoré sa generujú pri spustení API. Tu treba povedať, že pri použitom deploymente sa tieto logy neukladajú a ich účel bol len pre identifikáciu chýb pri vývoji.

Nasadenie do GCP cez Docker

Pre nasadenie API do produkcie (na Google Cloud Platform) používame Docker, čo nám zaručuje, že aplikácia bude fungovať identicky lokálne aj v produkcii. Použitím docker-compose.yaml a Dockerfile máme jednoduchý spôsob ako API spustiť a spravovať v rôznych prostrediach.

Docker-compose.yaml súbor definuje jednoduchú konfiguráciu pre spustenie API služby v Docker kontajnery. Tento súbor obsahuje aj definíciu siete a portu, na ktorom bude API dostupné. V našom prípade je to port 8000.

version: '3'

services:
  api:
    build: .
    container_name: predict
    volumes:
      - ./:/app
    environment:
      - PORT=${PORT:-8000}
      - HOST=${HOST:-0.0.0.0}
    ports:
      - "8000:8000"

Dockerfile obsahuje inštrukcie na vytvorenie Docker image, ktorý obsahuje všetky potrebné závislosti a knižnice pre spustenie API. Tento image je možné nasadiť na rôzne platformy.

FROM rocker/r-ver:latest

# install os dependencies
RUN apt-get update -qq
RUN apt-get install -y --no-install-recommends \
  git-core \
  libssl-dev \
  libcurl4-gnutls-dev \
  curl \
  libsodium-dev \
  libxml2-dev \
  && rm -rf /var/lib/apt/lists/*

# install pak alternatives to install.packages
RUN Rscript -e "install.packages('pak', repos = sprintf('https://r-lib.github.io/p/pak/stable'))"

# install latest plumber from github main branch
RUN Rscript -e "pak::pkg_install('rstudio/plumber@main')"

# install other R packages
RUN Rscript -e "pak::pkg_install(c('logger','tictoc', 'fs', 'httr', 'dplyr', 'workflows', 'bundle', 'xgboost'))"

# setup workspace
COPY . /app

WORKDIR /app

ENTRYPOINT ["Rscript"]

CMD ["app.R"]

EXPOSE 8000

Image následne vytvoríme pomocou príkazu:

docker compose build --no-cache api

Následne kontajner umiestnime na server, ktorý sme si vybrali na nasadenie. V našom prípade je to Google Cloud Platform.

Zavolanie API

Na úvod malé upozornenie: Prvé zavolanie môže trvať dlhšie kvôli cold startu.

{
  "predicted_price": 203338.1719
}

library(bslib)
library(bsicons)
library(httr2)
library(dplyr)
library(shiny)
library(shinybusy)

mun_list <- readRDS("data/municipalities.RDS")
cond_list <- readRDS("data/conditions.RDS")
cert_list <- readRDS("data/certificates.RDS")
type_list <- data.frame(
  type = c("1-izbový byt", "2-izbový byt", "3-izbový byt", "4-izbový byt", "5-izbový byt"),
  id = c("1_i_b", "2_i_b", "3_i_b", "4_i_b", "5_i_b")
)
prov_list <- data.frame(
  prov = c("Áno", "Nie"),
  id = c(1, 0)
)

layout_sidebar(
  height = 700,
  width = 700,
  sidebar =  sidebar(
    shiny::selectizeInput(
      'select_mun', 
      'Obec', 
      choices = mun_list$Obec,
      selected = mun_list$Obec[1],
      multiple = FALSE
    ),
    shiny::selectizeInput(
      'select_cond',
      'Stav',
      choices = cond_list$Stav,
      selected = cond_list$Stav[1],
      multiple = FALSE
    ),
    shiny::selectizeInput(
      'select_cert', 
      'Certifikát', 
      choices = cert_list$Certifikát,
      selected = cert_list$Certifikát[1],
      multiple = FALSE
    ),
    shiny::selectizeInput(
      'select_type', 
      'Typ bytu', 
      choices = type_list$type,
      selected = type_list$type[1],
      multiple = FALSE
    ),
    shiny::selectizeInput(
      'select_prov', 
      'Provízia v cene', 
      choices = prov_list$prov,
      selected = prov_list$prov[1],
      multiple = FALSE
    ),
    shiny::sliderInput(
      'area',
      'Rozloha (m2)',
      min = 50,
      max = 150,
      value = 70
    ),
  shiny::actionButton(
      "submit",
      "Zavolať API",
      icon = shiny::icon("calculator"),
      class = "btn-primary"
    )
  ),
  use_busy_spinner(spin = "flower",
                   color = "primary"),
  value_box(
    title = "Predikovaná cena",
    value = textOutput("prediction"),
    showcase = bs_icon("house"),
    max_height = "100px",
    width_full_screen = "4oopx"
  )
)

# URL API
api_url <- "https://appartments-model-api-api-217473566915.europe-central2.run.app/predict"

# Reaktívna funkcia pre získanie predikcie z API
predicted_price <- reactiveVal(NULL)

observeEvent(input$submit, {
  
  show_spinner()
  
  req(input$select_mun, input$select_cond, input$area, input$select_cert, input$select_type, input$select_prov)

type_valid <- type_list |> 
    filter(type == input$select_type) |> 
    pull(id)

provision_numeric <- prov_list |> 
    filter(prov == input$select_prov) |> 
    pull(id)

  response <- request(api_url) |> 
    req_url_query(
      name_nsi    = input$select_mun,
      condition   = input$select_cond,
      area        = input$area,
      provision   = provision_numeric,
      certificate = input$select_cert,
      type        = type_valid
    ) |> 
    req_perform() |> 
    resp_body_json()
  
  hide_spinner()

  predicted_price(response$predicted_price[1])

})


output$prediction <- renderText({
  req(predicted_price())
  paste0(format(round(predicted_price(), 0), big.mark = " ", decimal.mark = ","), 
        " €")
})