Skip to content

jonluca/USC-Class-Notifier-API

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

USC-Class Notifier API

USC Class Notifier API is a free to use web API for notifications for the number of spots available in each section at USC. It uses Express as its server and MongoDB as its database and is able to send out emails as needed. It also preserves security (more than enough for a project of this nature) by requiring email authentication for use.

Utilizing the API

There are only three end-points to soc. This service is open to any developers, provided they abide by the rate limits and license.

Registration

Endpoint Parameters
https://jldc.me/soc/notify POST: email, courseid, department, phone

A sample AJAX POST request looks like:

$.ajax({
    method: 'POST',
    url: "https://jldc.me/soc/notify",
    type: 'json',
    data: {
        email: email,
        courseid: courseid,
        department: department,
        phone: phone
    },
    success: function(data, textStatus, jqXHR) {
        //Handle data and status code here
    }
});
Field About
email Validated email address of user
courseid Section id of class they would like to be notified on (i.e. 31027)
department Department within USC in which that section resides
phone Optional phone parameter

Valid sample data:

Field About
email jdecaro@usc.edu
courseid 61400
department SI
phone 1234567890

This would be a valid request to be notified about section 61400 in the SI department. This class specifically maps to Changing Family Forms, a GE F. Any request missing any of these three parameters is discarded.

The response is based entirely off of the HTTP status code.

Status Code Error Type
200 Registered successfully
201 Registered successfully, did not send a verification email because user has already verified
400 Response data will contain a field error with details on the error
501 Database insertion error (contact jdecaro@usc.edu if you ever receive this error)

Unregistering

To manually remove a user from being notified of a section, you can use the remove endpoint.

Endpoint Parameters
https://jldc.me/soc/remove POST: email, key

A sample AJAX POST request looks like:

$.ajax({
    method: 'POST',
    url: "https://jldc.me/soc/notify",
    type: 'json',
    data: {
        email: email,
        key: key
    },
    success: function(data, textStatus, jqXHR) {
                //Handle data and status code here
    }
});
Field About
email Validated email address of user
key Random 32 character key sent with the original verification email

The response is based entirely off of the HTTP status code.

Status Code Error Type
200 Unregistered successfully
400 Response data will contain a field error with details on the error

Database schema

//Main schema. One entry per section per user
const schema = new mongoose.Schema({
    email: String,
    section: String,
    department: { //epartment
        type: String,
        default: ""
    },
    key: String, //random key for verification
    phone: { //date of insertion
        type: String,
        default: ""
    },
    date: { //date of insertion
        type: Date,
        default: new Date().toISOString()
    },
    email_sent: { //have they been sent an email for this section?
        type: Boolean,
        default: false
    },
    valid: { //Have they verified their email?
        type: Boolean,
        default: false
    },
    manually_delete: { //Did they request manual deletion? only available through API right now
        type: Boolean,
        default: false
    },
    text_enabled: { //Are text message notifs enabled?
        type: Boolean,
        default: false
    },
    ip: String,
    uid: String,
    semester: {
        type: String,
        default: semester
    }
});


Field About
email Validated email address of user
section Section id of class they would like to be notified on (i.e. 31027)
department Department within USC in which that section resides
key 32 character random user key, used for verification and removal from database
phone The associated phone number for text message notifications
date Date of insertion, ISO-formatted string
email_sent soc_api defaults to only sending an email only once if spots open up for a class. If it sends an email, this gets set to true and they will not be notified if the class opens again in the future
valid Whether they've verified their email address by clicking on the verification email link
manually_delete Whether they've asked not to be notified manually, through the link in their email
text_enabled Whether to send text notifications for that user
semester Which semester they are registered for, according to USCs data (20173 is Fall 2017)

Web framework and Tech

This is be robust enough to handle something as small as the subset of students at USC that will utilize the chrome extension. If you have plans to expand or mass-market this API, please contact me.

There still needs to be major refactoring, as the current style is not up to par with industry style guidelines. This application works best in conjunction with USC Schedule Helper

Logging

There are currently 3 log files implemented.

Log About
access.log Apache-like access logs for the HTTP server
department.log Logs that have anything to do with department fetching/refershing
notification.log Logs that have anything to do with user data, notifications, and default console output

Additionally, department.log and notification.log have varying levels of logging. These indicate the severity of the log.

Level About
trace Generic information about entering functions, moving within the codebase, and on any action. Fairly noisy
debug Helpful debugging information
info General information on the application, including most unique/interesting logs
warn An error might have occurred, or possibly something unexpected.
error An error occurred. Highest severity, requires investigation

Rate Limits

You are limited to 100 calls per 15 minute period.

Notes by author

This API is free to use and will be maintained at least until December 2018 (when the author graduates). If any CS student is interested in taking over the project or contributing, feel free to make a pull request.

Additionally I've changed the refresh rate to 45 minutes over the summer so as to not hammer the USC servers.