On this page

Getting started

Once you have a deployed a R language Shaip, you can access the code in the source repository and can pull it to a folder to run on your machine, check out this link for a refresher on accessing the source cloud repository. The next step is to start developing your algorithm. The following provides details on using RStudio to develop and commit your R code as well as providing details on how to manage the environment and test your code.

Using RStudio to manage and develop your R Shaip code

Open R studio and then access the local folder with your code using the ‘Open Project ….’ button.

When you open the folder RStudio will automatically recognise that the folder is linked to a source repository and provide the options to manage your code using Git for example to commit, push and pull your code.

Package management using renv

In your project you will see a number of files and folders. Before starting you will need to setup your project to use renv to manage any packages that you need for your model. Details on what renv is and does can be found on the RStudio site see details below.

https://rstudio.github.io/renv/

The renv package is installed and ready to go and ensures the packages you use when developing locally are available when your Shaip is deployed and available publicly. The code is already to go and renv is initialised all you need to do is make sure the packages are installed locally. The deployment comes with a set of base packages which are cached so if you run:

#Restore the packages from the cache to run in your local environment
renv::snapshot()

This command runs very quickly and will give you access to the base packages. If you need to install new packages then you need to run the install package command and then make sure the lockfile (renv.lock) is updated. The lockfile keeps track of the packages and is used to update the local environment when your cloud version is pushed. So to install a package update the lockfile and make sure you have your local environment up to date run:

#Install a package.
renv::install("package-name")

#Update the lockfile - this is the file that keeps a record of all the packages you are using.
renv::snapshot()

#Make sure the packages you are using are upto date with the lockfile
renv::restore()

When you push your code, if you have run these commands the cloud build out is taken care of all the updates automatically.
When you start working on the code it is worth making sure both your code is up to date and the packages are also up to date. To get the latest code from the repository you can run the following from the command line:

git pull

Then run the renv command from the R console

#Update packages.
renv::restore()

Once this is done you are ready to get coding.

Developing and testing the API using plumber

Setting up and running plumber

The development environment for R based algorithms uses the plumber package. This allows R code to be accessed via a web API. Details on plumber can be found at:

https://www.rplumber.io/

The starting point for your R code is the file named rest_controller.R this sits under the rAlgoAPI/API/ folder.

The starting function provides a simple return of the input json body. RStudio recognises the code is using plumber and provides the run command as ‘Run API’.

When the ‘Run API’ is clicked it runs the R code on the local host and assigns a port in the above example it is port 6172 and local host is assigned to http://127.0.0.1, in addition the plumber code assigns /shaip as the endpoint and nominates that it is a POST command i.e. it will expect data in the body. All Shaip endpoints require data even if it is only to trigger a simulation. The console also shows that plumber is running and provides an option to stop when local testing is finished. Information on the API is shown in the viewer using swagger documentation.

Testing the API using Postman

Postman provides a useful tool for testing API integration and can be run as a standalone application or through a web browser. Most importantly it allows you to quickly and easily test your R code. We’ll be providing more detailed tutorials on the application of APIs, including how to use Postman to test your cloud based Shaip. In the meantime the following provides an overview of running Postman to test your local code, you will need to make sure you are either running the local app version of Postman or install the Postman agent to allow Postman to interact with your the local plumber host:

Postman documentation overview | Postman Learning Center

To start with we will provide a quick overview of using Postman to interact with your R plumber API. Once signed up for Postman you will be able to access your workspace and select to make an API request:

The above example shows the url endpoint with a POST call and includes a json body that is passed through the running plumber local server. The local base R code is now accessing the body converting it into a dataframe and then passing it back as a serialised JSON object in the body of the return.

# Add any packages that might be needed.
library(plumber)
library(jsonlite)
library(httr)

# Plumber decoration that is used to configure the API including defining endpoint and what format the data is returned.

#* Echo the parameter that was sent in
#* @serializer unboxedJSON
#* @post /shaip

# The main function that receives the JSON body as req$body and returns the result as res$body. The @seriealizer converts the dataframe to JSON. 
# The JSON return body allows users to interact with the API using restful API standards.
# When developing the local API it can be useful to print the input data to see the format. The print output will show up in the RStudio console when the API is accessed.
# The plumber function provides a wrapper for any R code to be developed and any code within this function will run when the API is called.

function(req, res) {
test1 <- toJSON(req$body)    
test <- fromJSON(test1) 

print(test)    

res$body <- test
}

The starting framework allows you to develop, run and test your R code locally. The plumber environment provides a wrapper for your code to be accessed using a standard restful API environment. When your R code is ready and you push your Shaip to the Shaipup dashboard it can be accessed by any language and you will be able to control who accesses it. It is important to note that the local development doesn’t include any of the Shaipup security wrappers. Once you push your code to the cloud this get’s automatically implemented and includes developing your data input schema to ensure all data is checked before being passed to your Shaip.

Summary

Pull your code from your source repository to a local folder.
Open the folder as a project in RStudio, make sure the Git option is available in RStudio.
Setup renv to manage packages.
Open the file ./rAlgoAPI/API/rest_controller.R and use the ‘Run API’ button to activate the base code making sure to note the port number allocated to the local host API.
Use Postman either via the web app with the downloaded agent or a local downloaded app to connect and run your API.
You are now ready to start developing and testing a local version of your R Shaip.