Dynamic Open API (Swagger) Client for R
OTHER License
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.
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")
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.
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))
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))
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)
})
))
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)
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)