Repository files navigation

This is a complete rewrite ofplumber. Thepurpose of the rewrite is to take everything we’ve learned from plumber,shed the bad decision that you inevitably make over the course ofdevelopment, and start from scratch.

You’ll find that plumber2 is very similar to plumber in a lot of ways,but diverts in key areas, resulting in API incompatibility between thetwo packages. Because of this you may need to update your plumber APIsif switching to plumber2.

plumber2 can be installed from CRAN usinginstall.packages("plumber2"). Alternatively you can install thedevelopment version from github using pak

# install.packages("pak")pak::pak("posit-dev/plumber2")

Below is a simple “hello world” API written for plumber2 thatillustrates some of the differences from plumber:

#* Echo the parameter that was sent in#*#* @get /echo/<msg>#*#* @param msg:string The message to echo back.#*#* @response 200:{msg:string} A string containing the input message#*function(msg) {list(msg= paste0("The message is: '",msg,"'")  )}#* Plot out data from the palmer penguins dataset#*#* @get /plot#*#* @query spec:enum|Adelie, Chinstrap, Gentoo| If provided, filter the#* data to only this species#*#* @serializer png{width = 700, height = 500}#* @serializer jpeg{width = 700, height = 500}#*#* @asyncfunction(query) {myData<-penguinstitle<-"All Species"# Filter if the species was specifiedif (!is.null(query$spec)){title<- paste0("Only the '",query$spec,"' Species")myData<- subset(myData,species==query$spec)if (nrow(myData)==0) {      abort_internal_error("Missing data for {query$spec}")    }  }  plot(myData$flipper_len,myData$bill_len,main=title,xlab="Flipper Length (mm)",ylab="Bill Length (mm)"  )}

Above you can both see some breaking changes and some new features inaction. The biggest breaking change is that parameters coming from thepath, the query string, and the body are now clearly separated. Onlyparameters from the path are provided as direct arguments to the handlerfunction. Query and body parameters are accessible through thequeryandbody argument respectively. As can be seen above they also usedifferent tags in the documentation.

Speaking of documentation, the parsing of plumber blocks have beengreatly improved. It is now built upon roxygen2, so it follows thatconvention, allowing multiline tags and defaulting to the first line astitle and proceeding untagged lines as description. The ability todefine input and output types has also been greatly expanded, adding theability to define nested objects, adding default values and (as seenabove) define enum (factors) to name a few. All input will get typechecked and default value imputed if missing.

For the/plot handler you can also see that it specifies multipleserializers. Doing so will allow the client to request its preferredresponse format using theAccept header. plumber2 will then performcontent negotiation to figure out the best response format based on whatit supports and what the client prefers.

Lastly, you can see a new tag (one of many) in the/plot handler.@async allows you to convert your handler into an async handlerautomatically. It is still possible to create an async handler manuallyby returning a promise, but the new tag significantly simplifies thisfor the most classic cases. There is still overhead involved in handlingrequests asynchronously so this is mainly a good idea for longer runninghandlers, but it is shown here as an example.