← Back to docs

On this page

Getting started

At the heart of a Shaip developed in R is the plumber package. Plumber provides a framework to handle HTTP requests and execute R code. The Shaipup platform provides a wrapper around the plumber that allows authenticated access, tracks usage, ensures appropriate response codes and validates all data being passed to each Shaip. HTTP requests have a structured framework and plumber routes the requests. A Shaip API constrains the endpoint to /shaip and it has to be a POST request with JSON data passed in the body. We reserve the parameter inputs to identify the Shaip owner and the Shaip name. This configuration helps simplify the R code and ensures users can easily access your Shaip and it minimises complexity for Shaip users.

Local versus deployed Shaips

• When working on developing and testing your local R Shaip you will get direct access to the R API framework. It is important to ensure the headers in /shaip are not changed:

• The serializer and post endpoint provide important information when the Shaip is deployed and should not be altered.

JSON inputs and return values

• Plumber takes care of getting the request (req) JSON input data into a dataframe and returning a dataframe as a JSON object in the response (res). While the initial Shaip has a toJSON and fromJSON function using the jsonlite package neither of these are necessary. To access the request data as a dataframe use req$body so that:

#* Manage Employees
#* @serializer unboxedJSON
#* @post /shaipfunction(req, res) {      
employees <- req$body

employees$Building <- c("Links", "Bright")

res$body <- employees

}

• for example the following JSON request body:

[
{"Name":"Bill", "Age": 35, "ID": "HP176"},
{"Name":"Heather", "Age": 27, "ID": "HP199"}
]

• will create an initial dataframe:

• The second command adds a Building allocation to each employee within the dataframe and updates the dataframe to:

• The final res.body returns the employees dataframe as a JSON object in the body of the HTTP response:

[
{"Name":"Bill", "Age": 35, "ID": "HP176", "Building": "Links"},
{"Name":"Heather", "Age": 27, "ID": "HP199", "Building": "Bright"}
]

• Because the R code is responding to a HTTP request the environment variable logs are not available to track the data processing steps. With large data manipulations and analysis it is useful to be able to track the outputs. To do this print statements can be inserted into the code and will then print to the console each time their is a HTTP request. For example the code below provides updates on the employees dataframe as it is developed through the code and shows that the Building information has been added to the dataframe:

#* Manage Employees
#* @serializer unboxedJSON
#* @post /shaip
function(req, res) {      
employees <- req$body
print(employees)
employees$Building <- c("Links", "Bright")
print(employees)
res$body <- employees

}

Summary

• Plumber handles the start and end of the R code via a HTTP request.
• Once the code is initiated any operations that can run in a R file can run within the plumber API function.
• Defining how you want the user to interact with the Shaip helps to determine what input and output data are required. The simple starting point is for a JSON input and JSON return. However, plumber provides tools and flexibility to generate a range of different return types for example a pdf report.