quickplumb: Quick Plumb API

#-----------------------------------------------------------------
# Example plumber.R script

require(quickplumb)
require(plumber)
require(dplyr)
require(RPostgreSQL)

drv <<- dbDriver("PostgreSQL")
sapply(dbListConnections(drv), dbDisconnect) # kill pre-existing db connections
con <<- dbConnect(drv, dbname = "mydb", host = "localhost", port = 5432, user = "username")

#' @apiTitle Quick Plumber API
#' @apiDescription Quick and flexible APIs in just a few lines


#' redirect API root to your Swagger API documentation page
#' @get /
#' @html
function(){'<meta http-equiv="refresh" content="0; URL=\'./__swagger__/\'" />'}


# DEMO IRIS API

# To create the db table for this example you can use:
# copy_to(con, iris, "iris", temporary = FALSE)

iris_pg <<- tbl(con, "iris")
iris_pg_names = names(collect(head(iris_pg, 1)))

#' iris dataset for demo & testing
#' @param ... "..." is a placeholder. All arguments are parsed as appropriate. NUMERICAL arguments are identified by starting with one of "<", ">", "~"  characters (~ changes to =), e.g: "Sepal.Length=>~7.1" is interpretted as ">=" (i.e. greater than or equal to).  STRING arguments (not starting ~/</>) are parsed with a boolean logic interpreter (using upper-case AND/OR operators) e.g: "Paris AND Berlin" or "Paris OR Berlin"; and recognises negation with "-" hyphen, e.g: "Species=-setosa".
#' @param resp_vars response variables - a special argument for the names of fields to include/omit in the response. e.g. return only "resp_vars=Species,Sepal.Length" or omit "resp_vars=-Species"
#' @param sort_vars variables to sort response by - e.g. "sort_vars=Species,Sepal.Length" (mutiple variables) or "sort_vars=-Petal.Length" (reverse order)
#' @param max_records Maximum data rows to return
#' @get /iris
quick_plumb(iris_pg, iris_pg_names, def_max_records = 100, hard_max_records = 150)


#-----------------------------------------------------------------


# To start your API(s) just navigate an R console to the plumber.R file's directory and run:

plumber::plumb()$run(port = 4444)

# Then navigate a browser to the endpoint generated by plumber

#-----------------------------------------------------------------

# The quick_plumb() function enables you to call, query and aggregate your dataset however
# you want (within limits of supported operations).  For PostgreSQL, "mean", "min" and "max"
# aggregations currently supported, in addition to counting with "dplyr::n()".

# Available API arguments:
# ...         - any data field can be queried with a boolean logical query or comparative/numerical filter
# _select     - equivalent to dplyr::select
# _group_by   - equivalent to dplyr::group_by
# _summarise  - equivalent to dplyr::summarise
# _count      - equivalent to dplyr::count, but relies on _group_by to define groupings
# _arrange_by - equivalent to dplyr::arrange
# max_records - maximum records to return (but overriden by quick_plumb(hard_max_records = ..))
# case_sen    - boolean querying ignores case by default. Providing this argument (e.g. case_sen=true) over-rides


# Example URL calls

# API root endpoint
http://127.0.0.1:4444/iris

# a boolean logical query (URL spaces are replaced by '%20' by the browser)
http://127.0.0.1:4444/iris?Species=setosa OR virginica

# a NOT query - i.e. omit setosa
http://127.0.0.1:4444/iris?Species=-setosa

# a numerical comparative filter ('~' becomes '=', so e.g. '>~' denotes greater-than and equal to)
http://127.0.0.1:4444/iris?Sepal.Length=>~7.0&Sepal.Length=<~7.5

# return specified fields only
http://127.0.0.1:4444/iris?_select=Sepal.Length,Sepal.Width

# return all fields except specified
http://127.0.0.1:4444/iris?_select=-Species

# sort matching data by field(s)
http://127.0.0.1:4444/iris?_arrange=Petal.Length,Petal.Width

# number of records to return (unless overriden by quick_plumb(hard_max_records=...))
http://127.0.0.1:4444/iris?max_records=10

# count rows by variable
http://127.0.0.1:4444/iris?_group_by=Species&_count=yes

# aggregate data by variable(s)
http://127.0.0.1:4444/iris?_group_by=Species&_summarise=mean:Sepal.Length,Sepal.Width+max:Petal.Length,Petal.Width