Programmatic Usage

Deprecation Warning

This section describes the behavior in Plumber prior to the 0.4.0 release. As of v0.4.0, this documentation is no longer valid. Please see here for updated documentation.

The easiest way to use plumber is by adding comments to decorate your existing functions, as you’ve likely seen throughout the examples and documentation here. There is, however, another approach that you can use to define behavior in plumber. This approach may be useful if you need to completely wrap up the execution of a plumber server in an executable script, rather than relying on files to be saved with particular names. If you don’t have such a use-case in mind, the comment-based approach will certainly be an easier way to get started.

The programmatic approach allows you to create a plumber router by hand without having to specify a source file that defines the behavior. You can actually start either approach via the plumber::plumber$new() constructor. You can optionally provide a file location to this function – which is also available via the shortcut plumb("filename.R"), or you can call the constructor with no arguments. If you don’t specify a file name, you’ve created a “blank” router, to which you can later add functionality.

Adding functionality to a router relies primarily on two functions: addEndpoint() and addFilter() which, as you might suspect, add endpoints and filters to your router. The details on the parameters of each of these functions is available in the comparison below.

Programmatic

        library(plumber)

# Create a new router
router <- plumber::plumber$new()

# An expression that defines the behavior of the filter
logFilter <- expression(
  function(req){
    print(paste0(date(), " - ", req$REMOTE_ADDR, " - ",
            req$REQUEST_METHOD, " ", req$PATH_INFO))
    forward()
  }
)
# addFilter() accepts the following parameters:
#   @param name The name of the filter
#   @param expr The expression encapsulating the
#     filter's logic
#   @param serializer (optional) A custom serializer
#     to use when writing out data from this filter.
#   @param processors The \code{\link{PlumberProcessor}}s
#     to apply to this filter.
router$addFilter(name="logger", expr=logFilter)

# An expression that defines the behavior of the endpoint
endExpr <- expression(
  function(){
    return("response here")
  }
)

# addEndpoint() accepts the following parameters:
#  @param verbs The verb(s) which this endpoint supports
#  @param path The path for the endpoint
#  @param expr The expression encapsulating the
#   endpoint's logic
#  @param serializer The name of the serializer to
#    use (if not the default)
#  @param processors Any \code{PlumberProcessors} to
#    apply to this endpoint
#  @param preempt The name of the filter before which
#    this endpoint should be inserted. If not specified
#    the endpoint will be added after all the filters.
router$addEndpoint(verbs=c("GET", "POST"), path="/",
                   expr = endExpr)

router$run(port=8000)

      

Comment Decorators

        # plumber-logger.R

#! @filter logger
function(req){
  print(paste0(date(), " - ", req$REMOTE_ADDR, " - ",
               req$REQUEST_METHOD, " ", req$PATH_INFO))
  forward()
}

#! @get /
#! @post /
function(){
  return("response here")
}

      
The above file uses the more "traditional" plumber approach of decorating the existing functions with comments. You could parse and run this file using the following commands in R.
        library(plumber)
        router <- plumb("plumber-logger.R")
        router$run(port=8000)
      
This would produce the same results as the programmatic approach.