The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

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 to read the specification, get_operations to get client functions and get_schemas 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

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 and get_schemas

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. See add_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. When path 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 return response object (httr package). See httr content 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, 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_response argument 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

api

API definition

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

api

Api object

Value

A list of functions

Print API object

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

Print Operation

Description

Print Operation

Usage

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

Arguments

x

Operation

...

further arguments passed to or from other methods

Print Operation

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 to strwrap().

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 response object in httr package documentation)

Details

See get_operations 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)

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.