Swagger Client

rapiclient

knitr::opts_chunk$set(echo = TRUE, comment = "#", collapse = TRUE)

Access services specified in OpenAPI (formerly Swagger) format.

rapiclient is not a code generator. Client is generated dynamically as a list of R functions.

Installation

Install the current released version from CRAN:

install.packages("rapiclient")

Or get the current development version from github:

# install.packages("devtools")
devtools::install_github("bergant/rapiclient")

Usage

Prepare API Operations and Schemas

library(rapiclient)

This example uses the sample petstore service and its OpenAPI definition at (http://petstore.swagger.io/v2/swagger.json).

pet_api <- get_api(url = "http://petstore.swagger.io/v2/swagger.json")
operations <- get_operations(pet_api)
schemas <- get_schemas(pet_api)

Function get_operations returns a list of functions. Each function takes named arguments, converts the values to JSON according to API operation definition and performs a service call which returns a http response object.

Function get_schemas returns a list of functions where each function returns an object according to the related schema in the API.

Calling Service Operations

Find a Pet

Let's try to find a pet with Id = 42 (see operation definition):

res <- operations$getPetById(petId = 42)

res$status_code
str(httr::content(res))

New Pet

OK, there is no pet with Id = 42, so let's add a pet:

res <- 
  operations$addPet(
    id = 42,
    category = schemas$Category(
      id = 1,
      name = "Undefined"
    ),
    name = "Agrajag",
    photoUrls = list(),
    tags = list(
      schemas$Tag(id = 1, name = "Wild"),
      schemas$Tag(id = 2, name = "Furry")
    ),
    status = "available"
  )

res$status_code

Check:

res <- operations$getPetById(petId = 42)

res$status_code
str(httr::content(res))

Response Handlers

If all operations are handled identically (e.g. reading content or stop on http exception), it is more convenient to create the API functions with this functionality. get_operations accepts an optional handler function which must accept a httr response object as an argument.

Some handler functions are already predefined. For example content_or_stop returns a content or throws an exception.

operations <- get_operations(pet_api, handle_response = content_or_stop)

pet_data <- operations$getPetById(42)
str(pet_data)

Note that you can always trace the communication between client and server with httr::with_verbose:

httr::with_verbose({
  # get pet data
  pet_data <- operations$getPetById(42)
  # delete a pet entry
  operations$deletePet(api_key = "special-key", petId = 42)
})

cat(capture.output(type = "message",

  httr::with_verbose({
    # get pet data
    pet_data <- operations$getPetById(42)
    # delete a pet entry
    operations$deletePet(api_key = "special-key", petId = 42)
  })

))

Help on API Operations

The good news is that autocomplete in RStudio editor works fine with dynamically created functions. The bad news: R documentation is not available with help or ?. To lookup the operation definition just print the function (write it down without parenthesis):

Let's get help for getPetById:

operations$getPetById

More complicated addPet also describes the nested schemas:

operations$addPet

For more detailed operation description use the operation's "definition" attribute :

definition <- attr(operations$getPetById, "definition")
str(definition)

Using Additional Headers

Set additional http headers at the time of creating operation functions in get_operations function.

The following example uses New York Times API from developer.nytimes.com with API key authentication.

nyt_api <- get_api("http://developer.nytimes.com/top_stories_v2.json/swagger.json")

nyt_operations <- 
  get_operations( nyt_api, .headers = c("api-key" = Sys.getenv("NYT_API_KEY")))

res <- nyt_operations$Top_Stories(section = "science", format = "json")

res$status_code

content <- httr::content(res)
str(content, max.level = 1)