Chapter 8 Programmatic Usage

Typically, users define APIs using the “annotations,” or special comments in their API source code. It is possible to define a Plumber API programmatically using the same underlying R6 objects that get created automatically when you define your API using annotations. Interacting with Plumber at this level can offer more control and specificity about how you want your API to behave.

8.1 Creating and Controlling a Router

The centerpiece of Plumber is the router. Plumber routers are responsible for coordinating incoming requests from httpuv, dispatching the requests to the appropriate filters/endpoints, serializing the response, and handling errors that might pop up along the way. If you’ve been using annotations to define Plumber APIs, then you’ve already worked with Plumber routers as that’s what the plumb() command produces.

To instantiate a new Plumber router programmatically, you can call plumber$new(). This will return a blank Plumber router with no endpoints. You could call run() on the returned object to start the API, but it doesn’t know how to respond to any requests so any incoming traffic would get a 404 response. We’ll see momentarily how to add endpoints and filters onto this empty router. Alternatively, you can pass a file that contains your annotation-based Plumber API as the first parameter to create a router much like you do with plumb().

Be aware that Plumber routers do come with a handful of filters pre-configured. These built-in filters are used to do things like process properties of the incoming request like its cookies, POST body, or query string. You can specify which filters you want in your new router by overriding the filters parameter when creating your new router.

8.2 Defining Endpoints

You can define endpoints on your router by using the handle() method. For instance, to define a Plumber API that response to GET requests on / and POST requests on /submit, you could use the following code:

pr <- plumber$new()
pr$handle("GET", "/", function(req, res){
  # ...
})

pr$handle("POST", "/submit", function(req, res){
  # ...
})

The “handler” functions that you define in these handle calls are identical to the code you would have defined in your plumber.R file if you were using annotations to define your API.

The handle() method takes additional arguments that allow you to control nuanced behavior of the endpoint like which filter it might preempt or which serializer it should use. For instance, the following endpoint would use Plumber’s HTML serializer.

pr <- plumber$new()
pr$handle("GET", "/", function(){
  "<html><h1>Programmatic Plumber!</h1></html>"
}, serializer=plumber::serializer_html())

8.3 Defining Filters

Use the filter() method of a Plumber router to define a new filter:

pr <- plumber$new()

pr$filter("myFilter", function(req){
  req$filtered <- TRUE
  forward()
})

pr$handle("GET", "/", function(req){
  paste("Am I filtered?", req$filtered)
})

You can specify other options such as the serializer to use if the filter returns a value in the filter() method, as well.

8.4 Registering Hooks on a Router {router-hooks}

Plumber routers support the notion of “hooks” that can be registered to execute some code at a particular point in the lifecycle of a request. Plumber routers currently support four hooks:

  • preroute(data, req, res)
  • postroute(data, req, res, value)
  • preserialize(data, req, res, value)
  • postserialize(data, req, res, value)

In all of the above you have access to a disposable environment in the data parameter that is created as a temporary data store for each request. Hooks can store temporary data in these hooks that can be reused by other hooks processing this same request.

One feature when defining hooks in Plumber routers is the ability to modify the returned value. The convention for such hooks is: any function that accepts a parameter named value is expected to return the new value. This could be an unmodified version of the value that was passed in, or it could be a mutated value. But in either case, if your hook accepts a parameter named value, whatever your hook returns will be used as the new value for the response.

You can add hooks using the registerHook method, or you can add multiple hooks at once using the registerHooks method which takes a name list in which the names are the names of the hooks, and the values are the handlers themselves.

pr <- plumber$new()
pr$registerHook("preroute", function(req){
  cat("Routing a request for", req$PATH_INFO, "...\n")
})
pr$registerHooks(list(
  preserialize=function(req, value){
    print("About to serialize this value:")
    print(value)
    
    # Must return the value since we took one in. Here we're not choosing
    # to mutate it, but we could.
    value
  },
  postserialize=function(res){
    print("We serialized the value as:")
    print(res$body)
  }
))

pr$handle("GET", "/", function(){ 123 })

Making a GET request to / will print out various information from the three events for which we registered hooks.

8.5 Mounting & Static File Routers

Plumber routers can be “nested” by mounting one into another using the mount() method. This allows you to compartmentalize your API by paths which is a great technique for decomposing large APIs into smaller files.

root <- plumber$new()

users <- plumber$new("users.R")
root$mount("/users", users)

products <- plumber$new("products.R")
root$mount("/products", products)

This is the same approach used for defining routers that serve a directory of static files. Static file routers are just a special case of Plumber routers created using PlumberStatic$new(). For example

pr <- plumber$new()

stat <- PlumberStatic$new("./myfiles")

pr$mount("/assets", stat)

This will make the files and directories stored in the ./myfiles directory available on your API under the /assets/ path.

8.6 Customizing a Router

There are a handful of useful methods to be aware of to modify the behavior of a router. Using hooks to alter request processing has already been discussed, but additionally you can modify a router’s behavior using any of the following:

  • setSerializer() - Sets the default serializer of the router.
  • setErrorHandler() - Sets the error handler which gets invoked if any filter or endpoint generates an error.
  • set404Handler() - Sets the handler that gets called if an incoming request can’t be served by any filter, endpoint, or sub-router.