Literal Routes

Plumber supports different “routing” schemes which will direct incoming traffic to the appropriate endpoint. The simplest form is to use fixed text. For instance the following endpoint will receive all GET requests for /user/me.

#* @get /user/me
  return (list(id=1, name="Test User"))

Variable Routes

In addition to the literal routes shown above, variable-routing is also supported – enabling you to match incoming requests to corresponding routes more flexibly. The following example uses variable-routing.

userNames <- list(1="Test User", 2="Different User")

#* @get /user/<id>
  return (list(id=id, name=userNames[[id]]))

This endpoint would accept incoming traffic for requests like /user/1 or /user/someUser. You’ll notice that the variable in the path is surrounded by < and > tags, and is given the name of id; you can name your variables as you see fit. You’ll also notice that a corresponding variable named id will be made available to you in the parameters of the endpoint function definition. This parameter will include whatever value was specified in the path in the <id> position. So a GET request for /user/14 would evaluate the function with id="14" (as a character string).

You can even do more complex variable-routes such as…

#* @get /user/<from>/connect/<to>
function(from, to){
  # Do something with the `from` and `to` variables...

In both the literal routing and the untyped variable-routing shown above, all parameters will be provided to the function as a character string.

Typed Variable Routes

If you only intend to support a particular type of data for a parameter in your variable route, you can also specify that in the route.

#* @get /user/<id:int>
  if (id < 100) {
    # ...

#* @post /user/activated/<active:bool>
  if (active){
    # ...

Specifying types for your variables saves you the step of having to convert the incoming parameter from a character string to whatever type you need it to be in. It also ensures that only appropriate paths match the specified routes. For instance, given the route /user/<id:int>, the request for /user/someUser will not match, as "someUser" is not an integer.

The following variable-route types are available in plumber:

R Type Plumber Name
logical bool, logical
numeric double, numeric
integer int