rapiclient
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
# [1] 404
str(httr::content(res))
# List of 3
# $ code : int 1
# $ type : chr "error"
# $ message: chr "Pet not found"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
# [1] 200Check:
res <- operations$getPetById(petId = 42)
res$status_code
# [1] 200
str(httr::content(res))
# List of 6
# $ id : int 42
# $ category :List of 2
# ..$ id : int 1
# ..$ name: chr "Undefined"
# $ name : chr "Agrajag"
# $ photoUrls: list()
# $ tags :List of 2
# ..$ :List of 2
# .. ..$ id : int 1
# .. ..$ name: chr "Wild"
# ..$ :List of 2
# .. ..$ id : int 2
# .. ..$ name: chr "Furry"
# $ status : chr "available"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)
# List of 6
# $ id : int 42
# $ category :List of 2
# ..$ id : int 1
# ..$ name: chr "Undefined"
# $ name : chr "Agrajag"
# $ photoUrls: list()
# $ tags :List of 2
# ..$ :List of 2
# .. ..$ id : int 1
# .. ..$ name: chr "Wild"
# ..$ :List of 2
# .. ..$ id : int 2
# .. ..$ name: chr "Furry"
# $ status : chr "available"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)
})# NULL
# -> GET /v2/pet/42 HTTP/1.1
-> Host: petstore.swagger.io
-> User-Agent: libcurl/7.51.0 r-curl/2.3 httr/1.2.1
-> Accept-Encoding: gzip, deflate
-> Content-Type: application/json
-> Accept: application/json
->
<- HTTP/1.1 200 OK
<- Date: Tue, 14 Feb 2017 09:15:55 GMT
<- Access-Control-Allow-Origin: *
<- Access-Control-Allow-Methods: GET, POST, DELETE, PUT
<- Access-Control-Allow-Headers: Content-Type, api_key, Authorization
<- Content-Type: application/json
<- Connection: close
<- Server: Jetty(9.2.9.v20150224)
<-
-> DELETE /v2/pet/42 HTTP/1.1
-> Host: petstore.swagger.io
-> User-Agent: libcurl/7.51.0 r-curl/2.3 httr/1.2.1
-> Accept-Encoding: gzip, deflate
-> Content-Type: application/json
-> Accept: application/json
-> Content-Length: 0
->
<- HTTP/1.1 200 OK
<- Date: Tue, 14 Feb 2017 09:15:56 GMT
<- Access-Control-Allow-Origin: *
<- Access-Control-Allow-Methods: GET, POST, DELETE, PUT
<- Access-Control-Allow-Headers: Content-Type, api_key, Authorization
<- Content-Type: application/json
<- Connection: close
<- Server: Jetty(9.2.9.v20150224)
<-
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
# getPetById
# Find pet by ID
# Description:
# Returns a single pet
#
# Parameters:
# petId (integer)
# ID of pet to returnMore complicated addPet also describes the nested schemas:
operations$addPet
# addPet
# Add a new pet to the store
#
# Parameters:
# id (integer)
# category (Category)
# name (string)
# photoUrls (array[string])
# tags (array[Tag])
# status (string)
# pet status in the store
# Category
# id (integer)
# name (string)
# Tag
# id (integer)
# name (string)For more detailed operation description use the operation's "definition" attribute :
definition <- attr(operations$getPetById, "definition")
str(definition)
# List of 10
# $ tags : chr "pet"
# $ summary : chr "Find pet by ID"
# $ description: chr "Returns a single pet"
# $ operationId: chr "getPetById"
# $ produces : chr [1:2] "application/xml" "application/json"
# $ parameters :List of 1
# ..$ :List of 6
# .. ..$ name : chr "petId"
# .. ..$ in : chr "path"
# .. ..$ description: chr "ID of pet to return"
# .. ..$ required : logi TRUE
# .. ..$ type : chr "integer"
# .. ..$ format : chr "int64"
# $ responses :List of 3
# ..$ 200:List of 2
# .. ..$ description: chr "successful operation"
# .. ..$ schema :List of 1
# .. .. ..$ $ref: chr "#/definitions/Pet"
# ..$ 400:List of 1
# .. ..$ description: chr "Invalid ID supplied"
# ..$ 404:List of 1
# .. ..$ description: chr "Pet not found"
# $ security :List of 1
# ..$ :List of 1
# .. ..$ api_key: list()
# $ path : chr "/pet/{petId}"
# $ action : chr "get"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
# [1] 200
content <- httr::content(res)
str(content, max.level = 1)
# List of 6
# $ status : chr "OK"
# $ copyright : chr "Copyright (c) 2017 The New York Times Company. All Rights Reserved."
# $ section : chr "science"
# $ last_updated: chr "2017-02-14T04:07:28-05:00"
# $ num_results : int 26
# $ results :List of 26