README.md

In chrishaid/deanslistr: An R package that wraps DeansList's RESTful HTTP API

deanslistr is an R package that wraps the DeansList RESTful HTTP API for use in R programming. It is currently under active development by Chris Haid at KIPP Chicago with the hope of releasing it on CRAN.

Installation

Installation is easy:

if(!require(devtools)) install_packages('devtools')
#> Loading required package: devtools

devtools::install_github('chrishaid/deanslistr')
#> Skipping install of 'deanslistr' from a github remote, the SHA1 (85292773) has not changed since last install.
#>   Use `force = TRUE` to force installation

Basic Usage

Usage is straightforward for version 1 API endpoints. You simply pass the last portion the endoint path to the endpoint paramater of the deanslist_api() function, along with your domain and API access key:

library(deanslistr)

dla_key <- Sys.getenv("KEY_DLA")

x <- deanslist_api(endpoint = 'suspensions',
                   domain = 'dlacademy',
                   key = dla_key)
#> No encoding supplied: defaulting to UTF-8.

x
#> <GitHub api/v1/suspensions>
#> List of 2
#>  $ rowcount: int 494
#>  $ data    :'data.frame':    494 obs. of  58 variables:
#>   ..$ SuspensionID            : chr [1:494] "1" "4" "11" "12" ...
#>   ..$ SchoolID                : chr [1:494] "9" "9" "9" "9" ...
#>   ..$ StudentID               : chr [1:494] "1769" "1767" "1747" "1764" ...
#>   ..$ StudentFirst            : chr [1:494] "Franco" "Jon" "Lawrence" "Lena" ...
#>   ..$ StudentMiddle           : chr [1:494] "" "" "" "" ...
#>   ..$ StudentLast             : chr [1:494] "Barron" "Acevedo" "Bartlett" "Charles" ...
#>   ..$ Gender                  : chr [1:494] NA "" "M" NA ...
#>   ..$ StudentSchoolID         : chr [1:494] "M-1826714" "M-1527896" "M-1427693" "F-440537" ...
#>   ..$ GradeLevelShort         : chr [1:494] "4th" "4th" "4th" "4th" ...
#>   ..$ HomeroomName            : chr [1:494] NA "UMass" NA NA ...
#>   ..$ SITypeID                : chr [1:494] "0" "0" "0" "0" ...
#>   ..$ Infraction              : chr [1:494] NA NA NA NA ...
#>   ..$ LocationID              : chr [1:494] NA NA NA NA ...
#>   ..$ CategoryID              : chr [1:494] NA NA NA NA ...
#>   ..$ Category                : chr [1:494] NA NA NA NA ...
#>   ..$ ReportedDetails         : chr [1:494] NA NA NA NA ...
#>   ..$ AdminSummary            : chr [1:494] NA NA NA NA ...
#>   ..$ ReturnPeriod            : chr [1:494] "1" "5" "1" "5" ...
#>   ..$ Context                 : chr [1:494] "Franco punched Steve Vargas in the face during lunch on 11/2.  Steve had 2 get 2 stitches." "Jon was a continuous today after yesterday's referral." "Larry learned an ISS for gross disrespect to staff." "Lena earned a 2 period ISS after earning 3 referrals last week.  She did a great job and is returning to class this afternoon." ...
#>   ..$ AddlReqs                : chr [1:494] "Franco must write a letter of apology to Steve and his parents." "Family meeting after school on Friday." "None at this time." "None" ...
#>   ..$ StatusID                : chr [1:494] NA NA NA NA ...
#>   ..$ Status                  : chr [1:494] NA NA NA NA ...
#>   ..$ FamilyMeetingNotes      : chr [1:494] "Franco's parents were extremely upset and apologetic about the incident." "" "None at this time." "None at this time." ...
#>   ..$ FollowupNotes           : chr [1:494] "Ensure Franco does not exhibit any more overly aggressive or violent behavior." "" "Ms. Johnson to follow up w/ parents." "At Ms. Gonzalez discretion." ...
#>   ..$ CreateBy                : chr [1:494] "35" "35" "114" "114" ...
#>   ..$ CreateFirst             : chr [1:494] "Leslie" "Leslie" "Matt" "Matt" ...
#>   ..$ CreateMiddle            : chr [1:494] "" "" "" "" ...
#>   ..$ CreateLast              : chr [1:494] "Riva" "Riva" "Robins" "Robins" ...
#>   ..$ CreateTitle             : chr [1:494] "Mr." "Mr." "Mr." "Mr." ...
#>   ..$ UpdateBy                : chr [1:494] NA NA NA NA ...
#>   ..$ UpdateFirst             : chr [1:494] NA NA NA NA ...
#>   ..$ UpdateMiddle            : chr [1:494] NA NA NA NA ...
#>   ..$ UpdateLast              : chr [1:494] NA NA NA NA ...
#>   ..$ UpdateTitle             : chr [1:494] NA NA NA NA ...
#>   ..$ Penalties               :List of 494
#>   .. .. [list output truncated]
#>   ..$ Actions                 :List of 494
#>   .. .. [list output truncated]
#>   ..$ Authorship              : logi [1:494] NA NA NA NA NA NA ...
#>   ..$ IsReferral              : logi [1:494] FALSE FALSE FALSE FALSE FALSE FALSE ...
#>   ..$ SendAlert               : logi [1:494] NA NA NA NA NA NA ...
#>   ..$ Location                : chr [1:494] NA NA NA NA ...
#>   ..$ IssueTS.date            : chr [1:494] "2013-11-08 20:11:00" "2013-11-18 22:51:00" "2013-11-18 12:04:00" "2013-11-18 12:05:00" ...
#>   ..$ IssueTS.timezone_type   : int [1:494] 3 3 3 3 3 3 3 3 3 3 ...
#>   ..$ IssueTS.timezone        : chr [1:494] "America/Chicago" "America/Chicago" "America/Chicago" "America/Chicago" ...
#>   ..$ ReturnDate.date         : chr [1:494] "2013-11-13 00:00:00" "2013-11-18 00:00:00" "2013-11-19 00:00:00" "2013-11-18 00:00:00" ...
#>   ..$ ReturnDate.timezone_type: int [1:494] 3 3 3 3 3 3 3 NA NA NA ...
#>   ..$ ReturnDate.timezone     : chr [1:494] "America/Chicago" "America/Chicago" "America/Chicago" "America/Chicago" ...
#>   ..$ CreateTS.date           : chr [1:494] "2013-11-10 20:13:58" "2013-11-17 22:53:36" "2013-11-18 12:05:16" "2013-11-18 12:07:07" ...
#>   ..$ CreateTS.timezone_type  : int [1:494] 3 3 3 3 3 3 3 3 3 3 ...
#>   ..$ CreateTS.timezone       : chr [1:494] "America/Chicago" "America/Chicago" "America/Chicago" "America/Chicago" ...
#>   ..$ UpdateTS.date           : chr [1:494] NA NA NA NA ...
#>   ..$ UpdateTS.timezone_type  : int [1:494] NA NA NA NA NA NA 3 NA NA 3 ...
#>   ..$ UpdateTS.timezone       : chr [1:494] NA NA NA NA ...
#>   ..$ ReviewTS.date           : chr [1:494] NA NA NA NA ...
#>   ..$ ReviewTS.timezone_type  : int [1:494] NA NA NA NA NA NA NA NA NA NA ...
#>   ..$ ReviewTS.timezone       : chr [1:494] NA NA NA NA ...
#>   ..$ CloseTS.date            : chr [1:494] NA NA NA NA ...
#>   ..$ CloseTS.timezone_type   : int [1:494] NA NA NA NA NA NA NA NA NA NA ...
#>   ..$ CloseTS.timezone        : chr [1:494] NA NA NA NA ...

Notice that while the deanslist_api() will try to coerce nested JSON to a data frame, some fields may be stored as lists (e.g., Penalties and Actions in the above response). So pay attion to the content that's returned; you might need to do some more munging with something like tidyr::unnest()

The remaing beta endpoints are taken processed on a case by case basis and require passing the endpoint_version = 'beta' to the deanslist_api():

x <- deanslist_api(endpoint = 'users',
                   domain = 'dlacademy',
                   key = dla_key,
                   endpoint_version = 'beta')
#> No encoding supplied: defaulting to UTF-8.

x
#> <GitHub api/beta/export/get-users.php>
#> List of 2
#>  $ rowcount: int 68
#>  $ data    :'data.frame':    68 obs. of  14 variables:
#>   ..$ DLSchoolID  : chr [1:68] "9" "9" "9" "9" ...
#>   ..$ SchoolName  : chr [1:68] "DeansList Academy" "DeansList Academy" "DeansList Academy" "DeansList Academy" ...
#>   ..$ DLUserID    : chr [1:68] "762" "763" "764" "1617" ...
#>   ..$ FirstName   : chr [1:68] "Andrea" "Bob" "VPCS" "Chris" ...
#>   ..$ MiddleName  : chr [1:68] "" "" "" "" ...
#>   ..$ LastName    : chr [1:68] "Roberts" "Parker" "Demo" "Habetler" ...
#>   ..$ Title       : chr [1:68] "Ms." "Mr." "Mr." "Mr." ...
#>   ..$ UserSchoolID: chr [1:68] "" "" "" "" ...
#>   ..$ UserStateID : chr [1:68] NA "" NA NA ...
#>   ..$ StaffRole   : chr [1:68] "" "" "" "" ...
#>   ..$ Username    : chr [1:68] "amorales" "bparker" "vpcs" "chrishabetler" ...
#>   ..$ Email       : chr [1:68] "[e-mail]" "" "[e-mail]" "[e-mail]" ...
#>   ..$ GroupName   : chr [1:68] "Teacher" "Teacher" "Teacher" "Teacher" ...
#>   ..$ Active      : chr [1:68] "Y" "Y" "Y" "Y" ...

Convenience Wrappers

The package has some convenience functions that wrap deanslist_api() for specific endpoints. These wrappers all start with a get_ prefix. The first (and curruntly only) wrapper is get_suspensions. The onus for these functions is to facilitate calling deanslist_api for multiple schools. If you have six schools you will need to provide 6 keys to deanslist_api, one-at-a-time. the get_ functions can take take multiple keys via the key_list parameter. Better still, you can store keys in .Renviron file, which will be sourced when R starts (if saved in a users home directory). The keys' variables need to fit hte pattern of DL_KEY_ where the SCHOOL bit can be any test string. get_ wrappers, if not passed a list of keys explicitely, will look to your environment variables for keys stored in the DL_KEY_ variables and requirest the data from DeansList and (try to) store the returned data as a list of data frames. This list of data frames is best handled with purrr or other tidyverse functions.

x <- get_suspensions(domain = 'dlacademy`)

chrishaid/deanslistr documentation built on May 13, 2019, 6:53 p.m.