TigerApps Resources Page

Purpose: List Princeton-specific data sources (along with helpful instructions on how to use these sources) for developers who want to create the next TigerApp.

Possible Pre-Requisites

Whitelist for CAS Authentication Use

If you intend to deploy your app and require CAS authentication on your app, you must make a request to OIT to whitelist your app’s host. Each time a user navigates to your app, your browser sends a request to fed.princeton.edu; your app’s host must be on the CAS whitelist for CAS authentication to proceed. Note that localhost is already on the CAS whitelist.

To whitelist your app, fill out this form.

Under Requested By, enter your name.
Under Service Name, enter your app’s host, e.g. https://myapp.herokuapp.com
Under More Information, type a sentence or two about your app’s name and purpose.
Answer the Slack Workspace question. Enter/select "unknown" for all remaining fields.

To use CAS Authentication in your app, you may follow this example from the TigerSnatch code.

Python CAS implementation: https://git.io/JRNLp
- You must cite authors Alex Halderman, Scott Karlin, Brian Kernighan, Bob Dondero in the header of your file.
Triggering login and getting netID in Python: https://git.io/JRNtn

Requesting A Service Account

Creating a service account netID allows your team to use the same netID to access OIT’s API Store and other CAS-authenticated apps, even after you graduate. The netID is meant to be used only with your app, and not any Princeton student/faculty.

To request a service account, file a ticket through OIT.

For Sponsor, enter the name of a Princeton faculty member. Note that creating and persisting a service account requires contacting a faculty sponsor (e.g. Prof. Robert Dondero) and asking them to sponsor your service account.
For Duration of Account, select Permanent if you intend for the app to exist in the long term.
For Business Reason, write your account’s purpose.
For Type of Account, select “General Use”. A new input called Additional Information will appear: here, you can request to have an Exchange mailbox for your service netID. Having an email address with your service account netID may be useful to your team (e.g. sending official emails from your app, collecting feedback from users).
For more help on completing the form, read OIT’s article.

Available Data Sources

OIT API Store

Once a service account has been created, you can use the APIs on OIT’s API Store: https://api-store.princeton.edu/store/. To access the site, you must be connected to the Princeton VPN or the Princeton eduroam WiFi network.

Login to OIT API store site
Click the Applications tab
1. Edit the name of the default application
Click on the APIs tab
1. Subscribe to an API by selecting an API, selecting your app’s name, then click Subscribe.

Available APIs

By default, the ActiveDirectory and PrincetonInfo APIs are available to you. To access the MobileApp API, you must send an email to the current Director for Software Infrastructure Services and ask them to add your service account netID to the approved accounts for the MobileApp API.

Consuming the APIs

Vinay Ramesh's GitHub repository contains (very) useful examples of calling these APIs in Python and Java. Here's a few tips for using this code:

Each folder in the root directory is named after an API. Click into your desired folder.
Click either "java" or "python" depending on the language you want.
For Java implementations, you must copy/paste the following files into your codebase: Configs.java and ReqLib.java. For Python, copy/paste these files: configs.py and req_lib.py. Feel free to make changes to these files, but be careful!
- Configs.java or configs.py contains essential API information coded as instance variables/attributes, including endpoints and keys.
- ReqLib.java or req_lib.py contains code to make an API request. One particularly useful method takes an endpoint and arguments, makes an API request, and returns a JSON response. For example, in MobileApp Java: https://git.io/JEsqo and in MobileApp Python: https://git.io/JEsqK
The remaining .java or .py files contain an example of using each of the API endpoints along with descriptive comments.

Note that the API store uses the OAuth3 security protocol to protect its endpoints. On each request to the API, you must pass an access token into the request header. Check out the ReqLib.java/req_lib.py files for an example. An access token lasts for one hour. To update the access token for your app, follow the code in Configs.java/configs.py (the useful method mentioned above in ReqLib.java and req_lib.py updates the access token automatically).

Along with an up-to-date access token, you’ll need the Consumer Key and the Consumer Secret. To get these keys, login to the OIT API Store > Applications > Production Keys. Click Generate Keys to generate your permanent Consumer Key and Consumer Secret. Store these keys securely in your app.

About the APIs

Active Directory

Endpoint	Parameter(s)	Response
/groups	name: name of group	Returns all users that belong to a group on campus, e.g. name = “Undergraduate Class of 2023” returns list of netids of students in class of 2023.
/users/full	uid: netid	Returns info about a user in the Princeton community, including full name, email, PUID, undergraduate or graduate or faculty, department, student or faculty, and groups that user belongs to. For faculty, also fetches title, phone number, and office location.
/users	uid: netid	Returns info about a user in the Princeton community, but only a subset of what is returned by /users/full.
/users/basic	uid: netid	Returns info about a user in the Princeton community, but only a subset of what is returned by /users.

PrincetonInfo

Endpoint	Parameter(s)	Response
/department	N/A	Returns full names of all departments within Princeton, e.g. “Art Museum”, “Computer Science”, "Pace Ctr for Civic Engagement".
/departments	N/A OR id: department id	An expanded version of /department. Returns name, id, short, and long description of given department, or all departments if none specified.

MobileApp

Endpoint	Parameter(s)	Response
/courses	term: term id subject: course department OR term: term id search: query that matches a course title, description, department code, or professor name.	Returns info on courses in the given term that either match the given subject or search query. Info includes course name, professor name, and list of course sections and each section’s name, time, enrollment.
/courses/terms	N/A	Returns info on the current term, including the term id, different formats of the term name, and the start and end date.
/dining/locations	categoryId: type of dining location, e.g. 2: dining halls, 6: amenities such as printers in each hall	Returns dining locations and in latitude and longitude of the given category.
/dining/menu	locationId: dining hall id menuId: breakfast, lunch, dinner	Returns a list of food items on the specified menu, including the id, name, description, link, and icons (e.g. vegan) of each item.
/places/open	N/A	Returns list of places and the name, id, and whether the place is open for each place.
/dining/events	placeId: id given to each place on campus	Returns given dining venue’s open hours.
/events/events	from: from date, to: to date	Returns open hours for dining venues.

Adding a new API

If none of the OIT APIs provides the data you need, then you may consider working with OIT to create a new API for a Princeton dataset. If interested, send an email to the current Director for Software Infrastructure Services and specify the dataset and its fields you are accessing, the input parameters for each endpoint, and permission from the data owner for OIT to gain access to their database. From there, you will work with OIT to create an API for the API store.

To learn more about OIT, visit https://oit.princeton.edu/get-started.

TigerBook API

This API, developed based on the TigerBook app, gives you access to information about undergraduate students you cannot find in the OIT Active Directory API, such as major, name, residential college, and photo.

Endpoint	See Docs
/api/v1/getkey/{agent}	https://github.com/alibresco/tigerbook-api/blob/master/README.md
/api/v1/undergraduates	https://github.com/alibresco/tigerbook-api/blob/master/README.md
/api/v1/undergraduates/{netid}	https://github.com/alibresco/tigerbook-api/blob/master/README.md

Princeton Art Museum API

This public API gives you access to information about objects in, packages in, and makers of the Princeton Art Museum’s collection. The API is well-documented here: https://github.com/Princeton-University-Art-Museum/puam-api-docs.

Endpoint	See Docs
/objects/{objectId}	https://github.com/Princeton-University-Art-Museum/puam-api-docs/blob/master/objects.md
/makers/{constituentId}	https://github.com/Princeton-University-Art-Museum/puam-api-docs/blob/master/makers.md
/packages/{packageId}	https://github.com/Princeton-University-Art-Museum/puam-api-docs/blob/master/packages.md
/search	https://github.com/Princeton-University-Art-Museum/puam-api-docs/blob/master/search.md

Other non-API data sources

Web scraping, e.g. scraping Course Offerings site for course grading policies.
Download floor plans from the housing website, with Princeton student login.

See source code for current TigerApps at https://www.tigerapps.org/

Huge thanks to Vinay Ramesh '20 for compiling usage information on many Princeton data sources and allowing this doc to reference his code examples.