Customization

Server customization

Behind a web server, the RestRserve endpoint passes received data to a "compute" function. This function, alongside some server parameters should be configured prior to deployment.

Configuration

File: config.yml

Located in the container/server subdirectory. Used to configure shared parameters between the Nginx web server and the RestRserve REST API server. Expects the following parameters:

• endpoint: Relative URL path to access server, an extension to the domain name. For example, if the endpoint is /task and the domain name is test.wustl.edu, then RestRserve will be accessible at test.wustl.edu/task. An endpoint is typically one indicative word.
• compute_function: File system path to the compute_function.R file, relative to the location of config.yml.
• port: Port number for RestRserve to listen and communicate on locally. Specified to route communications between RestRserve and the Nginx web server.
• output: Path to default folder to store log files.

Values in config.yml are propogated into the R server source code (start.R).

Default values:

default:
  endpoint: "/task"
  compute_function: "compute_function.R"
  port: 8000
  output: "data"

File: nginx.conf

Located in the container subdirectory, nginx.conf must be modified similarly to config.yml. Lines 21 - 27 define parameters for the proxy enabling the endpoint.

Default values:

server {
    server_name proxy;
    listen 80;
    location /task {
        proxy_pass "http://backend:8000/task";
    }
}

<endpoint> should be replaced with the path (including the /) specified in config.yml. <port> should be replaced with the port value specified in config.yml.

Template:

server {
    server_name proxy;
    listen 80;
    location <endpoint> {
        proxy_pass "http://backend:<port><endpoint>";
    }
}

Leave the remaining contents of nginx.conf unchanged.

Compute function

compute_function.R contains an empty R function that expects one parameter, request data.

compute_function <- function(request_data) {
  # The content of this function should parse the received request body
  # and execute computations and transformations as required
  request_data
}

When a request is passed on from Nginx, RestRserve extracts and clean the request data before passing it to compute_function. request_data is a list() of key-value pairs containing parameters specified in the request body.

Implement any data transformations or computations desired in this function. Ensure that the output (or just a single value) is returned at the end of compute_function. This value will be packaged by RestRserve and passed to Nginx, which returns a response to the task.

Example: Adding two numbers

Let's configure the server in a situation where we simply want to add two numbers together. The request to the server will contain two parameters, a and b, two integers to be added together. We also want the endpoint to be more descriptive than the default "/task". After making changes to the three files described below, the Docker service can be started.

config.yml

To use the endpoint /add instead, we need to change the value of endpoint to /add. The remaining parameters can be left unchanged. The resulting file will contain:

default:
  endpoint: "/add"
  compute_function: "compute_function.R"
  port: 8000
  output: "data"

nginx.conf

Since we have changed the endpoint, we must also change the proxy configuration. Update the endpoint specified in the configuration so the resulting file looks like this:

server {
    server_name proxy;
    listen 80;
    location /add {
        proxy_pass "http://backend:8000/add";
    }
}

compute_function.R

Some assumptions need to be made about the parameters passed in the body of the request to the custom function. In this case, let's assume that two parameters are specified, a and b. These will be passed inside the request_data object to compute_function, and the result of adding a and b can be returned:

compute_function <- function(request_data) {
  # Return the output of adding a and b
  as.numeric(request_data$a) + as.numeric(request_data$b)
}

Deployment

See the deployment documentation for instructions to deploy this example or another implementation of this template.