porcelain_endpoint: Basic endpoint object

porcelain_endpointR Documentation

Basic endpoint object

Description

Create a porcelain_endpoint object that collects together an HTTP method (e.g., GET), a path (e.g., /path) and a target R function. Unlike plumber endpoints, porcelain endpoints are meant to be used in testing.

Public fields

method

HTTP method

path

HTTP path

target

R function used for the endpoint

validate

Logical, indicating if response validation is used

inputs

Input control

state

Possibly mutable state

returning

An porcelain_returning object controlling the return type (content type, status code, serialisation and validation information).

Methods

Public methods


Method new()

Create an endpoint

Usage
porcelain_endpoint$new(method, path, target, ..., returning, validate = NULL)
Arguments
method

The HTTP method to support

path

The server path for the endpoint

target

An R function to run as the endpoint

...

Additional parameters, currently representing inputs. You can use the functions porcelain_input_query, porcelain_input_body_binary and porcelain_input_body_json to define inputs and pass them into this method. The names used must match those in target.

returning

Information about what the endpoint returns, as created by porcelain_returning

validate

Logical, indicating if any validation (implemented by the validate_response argument) should be enabled. This should be set to FALSE in production environments. By default (if validate is NULL), we look at the value of the environment PORCELAIN_VALIDATE - if true (case insensitive) then we will validate. This is intended to support easy use of validation on continuous integration systems.

validate_response

Optional function that throws an error of the processed body is "invalid".


Method run()

Run the endpoint. This will produce a standardised response object that contains status_code, content_type, body (the serialised output as run through the process method and returned by plumber) and data (the result of running the target function)

Usage
porcelain_endpoint$run(...)
Arguments
...

Arguments passed through to the target function


Method request()

Test the endpoint. This creates a full plumber object and serves one request to the endpoint. Argument are as passed through to porcelain's $request() method, except that method and path are automatically taken from the endpoint itself.

Usage
porcelain_endpoint$request(...)
Arguments
...

Arguments passed through to the request method (query, body and content_type).


Method plumber()

Helper method for use with plumber - not designed for end-user use. This is what gets called by plumber when the endpoint receives a request.

Usage
porcelain_endpoint$plumber(req, res, ...)
Arguments
req, res

Conventional plumber request/response objects

...

Additional arguments passed through to run


Method create()

Create a plumber endpoint

Usage
porcelain_endpoint$create(envir, validate)
Arguments
envir

Environment as used by plumber (currently unclear)

validate

Logical, allowing override of validation at the api level. This takes precedence over the value set when creating the endpoint.


Method clone()

The objects of this class are cloneable with this method.

Usage
porcelain_endpoint$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.


reside-ic/porcelain documentation built on March 4, 2024, 11:11 p.m.