porcelain: A 'porcelain' object

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

A porcelain object

Description

A porcelain object. This extends (via inheritance) a plumber object, and so only changes to the plumber API are documented here.

Super classes

plumber::Hookable -> plumber::Plumber -> porcelain

Methods

Public methods

• porcelain$new()

• porcelain$include_package_endpoints()

• porcelain$handle()

• porcelain$request()

• porcelain$clone()

Inherited methods

• plumber::Hookable$registerHooks()
• plumber::Plumber$addAssets()
• plumber::Plumber$addEndpoint()
• plumber::Plumber$addFilter()
• plumber::Plumber$addGlobalProcessor()
• plumber::Plumber$call()
• plumber::Plumber$filter()
• plumber::Plumber$getApiSpec()
• plumber::Plumber$getDebug()
• plumber::Plumber$mount()
• plumber::Plumber$onHeaders()
• plumber::Plumber$onWSOpen()
• plumber::Plumber$openAPIFile()
• plumber::Plumber$print()
• plumber::Plumber$registerHook()
• plumber::Plumber$removeHandle()
• plumber::Plumber$route()
• plumber::Plumber$run()
• plumber::Plumber$serve()
• plumber::Plumber$set404Handler()
• plumber::Plumber$setApiSpec()
• plumber::Plumber$setDebug()
• plumber::Plumber$setDocs()
• plumber::Plumber$setDocsCallback()
• plumber::Plumber$setErrorHandler()
• plumber::Plumber$setParsers()
• plumber::Plumber$setSerializer()
• plumber::Plumber$swaggerFile()
• plumber::Plumber$unmount()

---

Method new()

Create a porcelain object

Usage

porcelain$new(..., validate = FALSE, logger = NULL)

Arguments

...

Parameters passed to plumber

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.

logger

Optional logger, from the lgr package, perhaps created with porcelain_logger. If given, then we will log at the beginning and end of the request.

---

Method include_package_endpoints()

Include package endpoints

Usage

porcelain$include_package_endpoints(state = NULL, package = NULL)

Arguments

state

A named list of state, if your package requires any state-binding endpoints. Typically these will be mutable state (database connections, job queues, or similar). You must provide all states as required by the combination of all endpoints.

package

Either a package name or environment (optional, usually we'll find the right thing)

---

Method handle()

Handle an endpoint

Usage

porcelain$handle(...)

Arguments

...

Either a single argument, being a porcelain_endpoint object representing an endpoint, or arguments to pass through to plumber.

---

Method request()

Send a request to plumber for debugging

Sends a request to plumber so that the API can be easily tested without running the whole API. The interface here will probably change, and may end up using the interface of httr.

Usage

porcelain$request(
  method,
  path,
  query = NULL,
  body = NULL,
  content_type = NULL,
  request_id = NULL
)

Arguments

method

Name of HTTP method to use (e.g., GET)

path

Path to send the request to

query

Optional query parameters as a named list or character vector.

body

Optional body (only valid with PUT, POST, etc).

content_type

Optional content type (mime) which can be provided alongside body. If not provided it is set to application/octet-stream if body is raw, or application/json otherwise.

request_id

Optional request ID. An ID which is attached to every log raised by this request. Used for tracing purposes.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

porcelain$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

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