Service: RESTful service constructor

In Bioconductor/AnVIL: Bioconductor on the AnVIL compute environment

RESTful service constructor

Description

RESTful service constructor

Usage

Service(
  service,
  host,
  config = httr::config(),
  authenticate = TRUE,
  api_url = character(),
  package = "AnVIL",
  schemes = "https",
  api_reference_url = api_url,
  api_reference_md5sum = character(),
  api_reference_version = character(),
  api_reference_headers = NULL
)

Arguments

service	character(1) The Service class name, e.g., "terra".
host	character(1) host name that provides the API resource, e.g., "leonardo.dsde-prod.broadinstitute.org".
config	httr::config() curl options
authenticate	logical(1) use credentials from authentication service file 'auth.json' in the specified package?
api_url	optional character(1) url location of OpenAPI .json or .yaml service definition.
package	character(1) (default AnVIL) The package where 'api.json' yaml and (optionally) 'auth.json' files are located.
schemes	character(1) (default 'https') Specifies the transfer protocol supported by the API service.
api_reference_url	character(1) path to reference API. See Details.
api_reference_md5sum	character(1) the result of tools::md5sum() applied to the reference API.
api_reference_version	character(1) the version of the reference API. This is used to check that the version of the service matches the version of the reference API. It is usally set by the service generation function,. e.g., AnVIL::Rawls().
api_reference_headers	character() header(s) to be used (e.g., c(Authorization = paste("Bearer", token))) when retrieving the API reference for validation.

Details

This function creates a RESTful interface to a service provided by a host, e.g., "leonardo.dsde-prod.broadinstitute.org". The function requires an OpenAPI .json or .yaml specifcation as well as an (optional) .json authentication token. These files are located in the source directory of a pacakge, at ⁠<package>/inst/service/<service>/api.json⁠ and ⁠<package>/inst/service/<service>/auth.json⁠, or at api_url.

When provided, the api_reference_md5sum is used to check that the file described at api_reference_url has the same checksum as an author-validated version.

The service is usually a singleton, created at the package level during .onLoad().

Value

An object of class Service.

Examples

.MyService <- setClass("MyService", contains = "Service")

MyService <- function() {
    .MyService(Service("my_service", host="my.api.org"))
}

Bioconductor/AnVIL documentation built on Dec. 21, 2024, 6:17 a.m.