R function template and some basic tests for the API

README.md

About

Get the function out of the RMD file and start to put some structure to it.

Tear it apart.

To source the function

u = "https://gist.githubusercontent.com/Btibert3/c20c59a2b925562aa050/raw/f5a395239b78fc649432cfb6fcb7c22d8877225c/queryAPI.r"
devtools::source_url(u)

Ideas / To-do's

• A significantly more modular way of querying the data, especially when paging through results.
• Query more data
• input validation and error handling
• play with tidyjson

Error handling

• message if status != 200

queryAPI-tests.r

## tests - nhl feats
TOKEN = ""
league = "nhl"
sport = "hockey"
ep = "feats"
q_body = list(stat="shots", level="3")
feats3 = queryAPI(TOKEN, sport=sport, league=league, ep=ep, query=q_body, version=1)
names(feats3)

## tests - nba triple doubles
TOKEN = ""
league = "nba"
sport = "basketball"
ep = "stats"
q_body = list(stat="triple_double")
tripdubs = queryAPI(TOKEN, sport=sport, league=league, ep=ep, query=q_body, version=1, verbose=T)
names(tripdubs)
names(tripdubs$api_json)

## john scott stats
TOKEN = ""
league = "nhl"
sport = "hockey"
ep = "stats"
q_body = list(player_id="nhl-john-scott")
scott = queryAPI(TOKEN, sport=sport, league=league, ep=ep, query=q_body, version=1)
names(scott)
scott$stats[[1]]
# $id
# [1] "3b621d5f-7b33-4ea7-80c3-d55908e24cf9"
# 
# $created_at
# [1] "2015-12-05T02:57:44Z"
# 
# $updated_at
# [1] "2015-12-05T02:57:44Z"
# 
# $stat
# [1] "time_on_ice_secs"
# 
# $statistic_type
# [1] "HockeyPlayerStat"
# 
# $actual
# [1] "415.0"
# 
# $feat_id
# [1] "29db40ad-ef11-4bb5-a6a5-72e2ea9cb0fa"

queryAPI.r

#' Interface with the Stattleship API
#' 
#' A simple, generic function to query data from the API
#' 
#' @param token character. A valid token for the API
#' @param sport character. The sport, such as hockey, basketball, football
#' @param league character. NHL, NBA, etc.
#' @param ep character. The endpoint
#' @param query A list that defines the query parameters
#' @param version The API version. Current version is 1.
#' @param page numeric. The page number to request
#' @param verbose logical. For debugging, returns response and parsed response.
#' 
#' @examples 
#' \dontrun{
#' TOKEN = "aklsjdlfkajsfdas"
#' results = queryAPI(TOKEN, 
#'                    sport="hockey", 
#'                    query=list(player_id="akjasdf")
#'                    version = 1,
#'                    ep = "stats",
#'                    verbose = F)
#' 
#' @export
queryAPI = function(token, 
                    sport="hockey", 
                    league = "nhl", 
                    ep="stats", 
                    query=list(), 
                    version=1, 
                    walk=F,
                    page=NA,
                    verbose=F) {
  
  ## TODO:  walk the results if > 20 entries
  ## TODO:  test to validate data types
  ## TODO:  best practices on walking the data? Have # entries paramter? 
  
  ## packages :  doesnt feel like this is the right way to do it
  library(httr)
  
  ## build the URL and the endpoint
  URL = sprintf("https://www.stattleship.com/%s/%s/%s", sport, league, ep)
  
  ## the accept parameters.  Is there a better way to do this?
  ACCEPT = sprintf("application/vnd.stattleship.com; version=%d", version)
  
  ## if page is supplied, add it to the list
  if (!is.na(page) & is.numeric(page) & page >= 1) {
    query = c(query, page=page)
  }
  
  ## test the body to see if it is a list and has values
  ## if not, just return an empty list
  ## todo: test to ensure that query is a list if !is.na
  ## get the request from the API
  resp = GET(URL,
             add_headers(Authorization =TOKEN, 
                         Accept = ACCEPT, 
                         `Content-Type`="application/json"), 
             query=query)
  
  
  ## convert response to text first, do not use baseline httr::content default
  api_response = content(resp, as="text")
  
  ## use jsonlite::fromJSON
  api_response = jsonlite::fromJSON(api_response)
  
  ## if verbose = T, return a list that includes the parsed results
  ## and the original request
  if (verbose) {
    api_response = list(response =  resp,
                        api_json = api_response)
  }
  
  ## return the data
  return(api_response)
}