TigerApps Resources Page
This page is a collection of resources for Princeton students looking to build apps for the Princeton community. If you have any questions or need assistance, please reach out to the TigerApps team at [email protected].
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 implement CAS, view the documentation found here and/or use the following examples:
- Python CAS implementation: link
- 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: link
- SvelteKit CAS implementation: link
- This implementation is specific to the TigerStudy app, so you'd need to make a few modifications.
- It also uses the v3 CAS protocol to get user info beyond just the netID.
- Contact Joshua Lau '26 ([email protected]) for assistance.
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
- Edit the name of the default application
-
Click on the APIs tab
- 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.