porcelain_endpoint: Basic endpoint object

In reside-ic/porcelain: Turn a Package into an HTTP API

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

• porcelain_endpoint$new()

• porcelain_endpoint$run()

• porcelain_endpoint$request()

• porcelain_endpoint$plumber()

• porcelain_endpoint$create()

• porcelain_endpoint$clone()

---

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.