Help for package rapiclient (original) (raw)

Type: Package
Title: Dynamic OpenAPI/Swagger Client
Version: 0.1.8
URL: https://github.com/bergant/rapiclient
BugReports: https://github.com/bergant/rapiclient/issues
Description: Access services specified in OpenAPI (formerly Swagger) format. It is not a code generator. Client is generated dynamically as a list of R functions.
Depends: R (≥ 3.3.0)
License: MIT + file LICENSE
Imports: jsonlite, httr, tools, yaml
Encoding: UTF-8
RoxygenNote: 7.3.2
Suggests: testthat
NeedsCompilation: no
Packaged: 2024-09-30 16:59:49 UTC; mr148
Author: Darko Bergant [aut], Marcel Ramos ORCID iD [cre, ctb], Alexandru Mahmoud [ctb], Sean Davis [ctb], Martin Morgan [ctb]
Maintainer: Marcel Ramos marcel.ramos@sph.cuny.edu
Repository: CRAN
Date/Publication: 2024-09-30 21:10:02 UTC

rapiclient: Open API (Swagger) Client

Description

Create R functions directly from OpenAPI (formerly Swagger) specification.

Creating a client

Use [get_api](#topic+get%5Fapi) to read the specification,[get_operations](#topic+get%5Foperations) to get client functions and[get_schemas](#topic+get%5Fschemas) to create functions for additional schemas.

See usage example at https://github.com/bergant/rapiclient#rapiclient

Check out https://github.com/OAI/OpenAPI-Specification for additional information about Open API specification

Support

Please use https://github.com/bergant/rapiclient/issues for issues

Author(s)

Maintainer: Marcel Ramos marcel.ramos@sph.cuny.edu (ORCID) [contributor]

Authors:

Other contributors:

See Also

Useful links:

Examples

## Not run: 
# Read API description
api <- get_api(api_url)

# create operation and schema functions
operations <- get_operations(api)
schemas <- get_schemas(api)

# call service
operations$some_operation(x, y, schemas$some_structure(u, v, ...))

## End(Not run)

Build operations url

Description

Build operations operation url for specified parameter values

Usage

build_op_url(api, scheme, host, base_path, op_def, par_values)

Arguments

scheme http or https
host host name with port (delimited by ":")
base_path base path, defined in api specification
op_def a single operation definition
par_values parameter values in a list

See Also

[get_operation_definitions](#topic+get%5Foperation%5Fdefinitions)

Set default arguments

Description

Use this functions to simplify operation and schema functions with default arguments

Usage

set_default_args(f, ...)

set_default_args_list(f, arguments)

set_default_args_call(f_call)

Arguments

f function
... Parameters with default values
arguments A named list of arguments names and values
f_call A function call

Value

A function with new defaults on arguments

Get API

Description

Create API object from Swagger specification

Usage

get_api(url, config = NULL, ext)

Arguments

url API URL or file (can be json or yaml format)
config httr::config() curl options.
ext the file extension of the API file (either 'yaml' or 'json'). By default, it is obtained from the URL with 'tools::file_ext' and should be provided when the file URL is missing an extension.

Value

API object

See Also

See also [get_operations](#topic+get%5Foperations) and [get_schemas](#topic+get%5Fschemas)

Examples

## Not run: 
# create operation and schema functions
api_url <- "http://petstore.swagger.io/v2/swagger.json"
api <- get_api(api_url)
operations <- get_operations(api)
schemas <- get_schemas(api)

## End(Not run)

Message body

Description

Transform a list of operation arguments to an http request message body. This method searches for parameters with swagger / openAPI specification 'in: body' or 'in: formData'. 'body' parameters are expected to be R vectors or lists, and are transformed to JSON using 'jsonlite::toJSON()'. 'formData' parameters are treated as is, so must be specified (e.g., using 'httr::upload_file()') by the caller. Interpretation of 'formData' parameters require that the 'op_def' includes 'consumes: multipart/form-data'.

Usage

get_message_body(op_def, body, auto_unbox = TRUE)

Arguments

op_def A list representation of the swagger / openAPI description of the operation.
body A list representation of the operation arguments provided by the user.
auto_unbox automatically unbox() all atomic vectors of length 1. It is usually safer to avoid this and instead use the unbox() function to unbox individual elements. An exception is that objects of class AsIs (i.e. wrapped in I()) are not automatically unboxed. This is a way to mark single values as length-1 arrays.

Value

A JSON character representation (for 'body') or list of objects (for 'formData') representing the parameters 'x'.

Get Operations Definitions

Description

Get a list of operations definitions from API specification

Usage

get_operation_definitions(api, path = NULL)

Arguments

api API object
path (optional) filter by path

Details

Operations are parsed from 'paths“ element for every path and every action inside path. Operation name is set to 'operationId' from each action.

See also specification https://swagger.io/specification/#operationObject

Get operations

Description

Creates a list of functions from API operations definition. Names in a list are operationIDs from API.

Usage

get_operations(
  api,
  .headers = NULL,
  path = NULL,
  handle_response = identity,
  auto_unbox = FALSE
)

Arguments

api API object (see get_api)
.headers Optional headers passed to httr functions. Seeadd_headers documentation
path (optional) filter by path from API specification
handle_response (optional) A function with a single argument: httr response
auto_unbox automatically unbox() all atomic vectors of length 1. It is usually safer to avoid this and instead use the unbox() function to unbox individual elements. An exception is that objects of class AsIs (i.e. wrapped in I()) are not automatically unboxed. This is a way to mark single values as length-1 arrays.

Details

All functions return a response object from httr package or a value returned by handle_response function if specified. Whenpath is defined, only operations with the specified API path root are created. Use .headers parameters to send additional headers when sending a request.

Value

A list of functions.

Handling response

If no response handler function is defined, operation functions returnresponse object (httr package). See httrcontent documentation for extracting content from a request, and functions http_error and http_status how to handle http errors and error messages.

When using simple [result_handlers](#topic+result%5Fhandlers), operations will return the content of response instead of httr response object (or handle error as exception or warning in case of error).

To handle response automatically with custom function, define a function with httr response object as argument and pass it as handle_responseargument to get_operations function.

Examples

## Not run: 
# create operation and schema functions
api_url <- "http://petstore.swagger.io/v2/swagger.json"
api <- get_api(api_url)
operations <- get_operations(api)
schemas <- get_schemas(api)

# get operations which return content or stop on error
operations <- get_operations(api, handle_response = content_or_stop)

# use .headers when operations must send additional headers when sending
operations <-
  get_operations(api, .headers = c("api-key" = Sys.getenv("SOME_API_KEY")))

## End(Not run)

Get Parameters

Description

Extract all parameters from parameters definition as a list In case of reference to schema, use the schema.

Usage

get_parameters(api, api_parameters)

Arguments

Get schema graphviz dot (experimental in this version)

Description

Create a graphviz presentation of schema structure (experimental)

Usage

get_schema_graphviz_dot(
  api,
  schema,
  schema_name = NULL,
  rankdir = "LR",
  gv_attrs = ""
)

Arguments

api Api object
schema A schema definition from api (a list object)
schema_name A name of root schema

Get schema structure (experimental in this version)

Description

(experimental) Produces nodes and edges where nodes are a list of schemas, represented as data frames with schema properties and edges are relations between nested schemas

Usage

get_schema_structure(api, x, name = NULL)

Arguments

api Api object
x A schema definition from api (a list object)
name A name of root schema

Get schemas

Description

Returns a list of functions with arguments from API schemas. Elements are named by schema names, each function returns a named list.

Usage

get_schemas(api)

Arguments

Value

A list of functions

Description

Print API object

Usage

## S3 method for class 'rapi_api'
print(x, ...)

Arguments

x API object
... further arguments passed to or from other methods

Description

Print Operation

Usage

## S3 method for class 'rapi_operation'
print(x, ...)

Arguments

x Operation
... further arguments passed to or from other methods

Description

Print Operation

Usage

## S3 method for class 'rapi_schema_function'
print(x, ...)

Arguments

x Operation
... further arguments passed to or from other methods

Description

Print Operation

Usage

print_wrap(text, ...)

Arguments

text character(1) to be formatted to the width of the user screen, with additional arguments ... passed tostrwrap().

Simple functions to handle http response

Description

When creating operations from api one can define how the response from http should be handled. These functions can be used for simple result handling.

Usage

content_or_stop(x)

content_or_warning(x)

content_or_message(x)

Arguments

x A response object from httr package (see responseobject in httr package documentation)

Details

See [get_operations](#topic+get%5Foperations) for details.

Value

Content of http response

Functions

Examples

api_file <- system.file(
  "extdata", "sample_specs", "petstore.yaml",
  package = "rapiclient", mustWork = TRUE
)
api <- get_api(api_file)
operations <- get_operations(api, handle_response = content_or_stop)