In trestletech/plumber: An API Generator for R

source("_helpers.R")

Annotations {#annotations}

Annotations are specially-structured comments used in your plumber file to create an API. A full annotation line starts with #* or #', then the annotation keyword @..., any number of space characters followed by the content. It is recommended to use #* to differentiate them from roxygen2 annotations.

Global annotations {#global-annotations}

Global annotations can be used anywhere in your plumber file. They are independent from other annotations and do not require an expression.

Annotation | Argument | Description/References -----------| -------- | ---------------------- @apiTitle | Title | Info Object @apiDescription | Description | Info Object @apiTOS | TOS link | Info Object @apiContact | Contact object | Contact Object @apiLicense | License object | License Object @apiVersion | Version | Info Object @apiTag | Tag Description | Can be repeated to add multiple tags. Quote with " or ' to use non word character (like spaces) in Tag. Tag Object

Annotations example

#* @apiTitle Sample Pet Store App
#* @apiDescription This is a sample server for a pet store.
#* @apiTOS http://example.com/terms/
#* @apiContact list(name = "API Support", url = "http://www.example.com/support", email = "[e-mail]")
#* @apiLicense list(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0.html")
#* @apiVersion 1.0.1
#* @apiTag pet Pets operations
#* @apiTag toy Toys operations
#* @apiTag "toy space" Toys operations

Equivalent programmatic usage

pr() %>%
  pr_set_api_spec(function(spec) {
    spec$info <- list(
      title = "Sample Pet Store App",
      description = "This is a sample server for a pet store.",
      termsOfService = "http://example.com/terms/",
      contact = list(name = "API Support", url = "http://www.example.com/support", email = "[e-mail]"),
      license = list(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0.html"),
      version = "1.0.1"
    )
    spec$tags <- list(list(name = "pet", description = "Pets operations"), list(name = "toy", description = "Toys operations"), list(name = "toy space", description = "Toys operations"))
    spec
  })

Block annotations {#block-annotations}

A block of annotations is a combination of annotations that create either an endpoint, a filter, a static file handler or a Plumber object modifier. Block annotations are always followed by an expression.

Endpoint {#endpoint-block-annotations}

Annotation | Argument | Description/References -----------| -------- | ---------------------- @get, @post, @put, @use, @delete, @head, @options, @patch | Path | Endpoints, Dynamic Routes, Typed Dynamic Routes @serializer | Alias [Args list]] | Some serializers accept arguments. See serializers article and serializers reference. Aliases : r paste0("<code>", registered_serializers(), "</code>", collapse = ", ") from registered_serializers(). @parser | Alias [Args list] | Some parsers accept arguments. See parsers reference. Can be repeated to allow multiple parsers on the same endpoint. Aliases : r paste0("<code>", registered_parsers(), "</code>", collapse = ", ") from registered_parsers(). @param | Name[:Type Description] | Enclose Type between square brackets [] to indicate it is an array. Can be repeated to define different parameters. @response | Name Description | Simple Response object. Can be repeated to define different responses. @tag | Tag | Can be repeated to add multiple tags. Quote with " or ' to use non word character (like spaces) in Tag. Tag field @preempt | Filter | Specify that this endpoint has to execute before Filter. Filters None | Comments | First line without annotation will be mapped to Summary field subsequent lines will be mapped to Description field.

More details on @param

Types are used to define API inputs. You can use most of them in dynamic routes. Note that Plumber first look in block expression to set endpoint parameters names, types and default value. Then @param annotations and dynamic route/path defined parameters will override Plumber guesses from block expression.

Query parameters currently need to be explicitly converted as they are pushed as is (character) to block expression. Only dynamic route parameters are converted to specified @param type before being pushed to block expression.

Plumber parameter type to OpenAPI type reference. For programmatic use, pick the one with an asterisk.

Type | OpenAPI | Availability ---------------- | ----------- | --------- bool, boolean, logical | boolean | query, path dbl, double, float, number, numeric | number format:double | query, path int, integer | integer format:int64 | query, path chr, str, character, string | string | query, path list, data.frame, df, object | object | body file, binary | string format:binary | body

Annotations example

#* @get /query/parameters
#* @serializer text
#* @param name:str
#* @param age:[int]
function(name, age) {
  # Explicit conversion is required for query parameters
  age <- as.integer(age)
  sprintf("%s is %i years old", name, max(age))
}

#* @get /dyn/<name:str>/<age:[int]>/route
#* @serializer text
#* @parser none
#* @response 200 A sentence
function(name, age) {
  sprintf("%s is %i years old", name, age)
}

#* @post /upload_file
#* @serializer rds
#* @parser multi
#* @parser rds
#* @param f:file A file
#* Upload an rds file and return the object
function(f) {
  as_attachment(f[[1]], names(f)[1])
}

Equivalent programmatic usage

text_handler <- function(name, age) { sprintf("%s is %i years old", name, max(age)) }
qp_handler <- function(name, age) { age <- as.integer(age); text_handler(name, age) }
file_handler <- function(file) { as_attachment(file[[1]], names(file)[1]) }
pr() %>%
  pr_get(path = "/query/parameters",
         handler = qp_handler,
         serializer = serializer_text(),
         params = list("name" = list(type = "string", required = FALSE, isArray = FALSE),
                       "age" = list(type = "integer", required = FALSE, isArray = TRUE))) %>%
  pr_get(path = "/dyn/<name:str>/<age:[int]>/route",
         handler = text_handler,
         serializer = serializer_text(),
         parsers = "none",
         responses = list("200" = list(description = "A sentence"))) %>%
  pr_post(path = "/upload_file",
          handler = file_handler,
          serializer = serializer_rds(),
          parsers = c("multi", "rds"),
          params = list("file" = list(type = "file", desc = "A file", required = FALSE, isArray = FALSE)),
          comments = "Upload an rds file and return the object")

Filter {#filter-block-annotations}

Annotation | Argument | Description/References -----------| -------- | ---------------------- @filter | Filter name | Filters

Annotations example

#* @filter logger
function(req){
  cat(as.character(Sys.time()), "-",
    req$REQUEST_METHOD, req$PATH_INFO, "-",
    req$HTTP_USER_AGENT, "@", req$REMOTE_ADDR, "\n")
  plumber::forward()
}

Equivalent programmatic usage

pr() %>%
  pr_filter("logger", function(req){
    cat(as.character(Sys.time()), "-",
      req$REQUEST_METHOD, req$PATH_INFO, "-",
      req$HTTP_USER_AGENT, "@", req$REMOTE_ADDR, "\n")
    plumber::forward()
  })

Static File Handler {#static-block-annotations}

Annotation | Arguments | Description/References -----------| --------- | ---------------------- @assets | Directory [Mount path] | Static files

Annotations example

#* @assets ./files/static
list()

#* @assets ./files/static /static
list()

#* @assets ./files/static /
list()

Equivalent programmatic usage (note that argument order is reversed)

pr() %>%
  pr_static(direc = "./files/static")

pr() %>%
  pr_static("/static", "./files/static")

pr() %>%
  pr_static("/", "./files/static")

Plumber Router Modifier {#plumber-block-annotations}

Annotation | Arguments | Description/References -----------| --------- | ---------------------- @plumber | None | Modify plumber router from plumber file. The plumber router provided to the function must be returned. In most cases, anonymous functions are used following the #* @plumber annotation. However, named functions can also be used. When a named function is used, it must be referenced without parentheses.

Annotations example

#* @plumber
function(pr) {
  pr %>%
    pr_set_debug(TRUE) %>%
    pr_set_docs("swagger")
}

# Named function
debug_swagger <- function(pr) {
  pr %>%
    pr_set_debug(TRUE) %>%
    pr_set_docs("swagger")
}

#* @plumber
debug_swagger

Equivalent programmatic usage

pr() %>%
  pr_set_debug(TRUE) %>%
  pr_set_docs("swagger")

trestletech/plumber documentation built on May 6, 2024, 6:17 p.m.