Endpoint Map

[heartgg]

Overview

This discussion aims to create a structured list of endpoints and their intended uses. It will be helpful to developers to see what needs to be done and how to split up the development.
You can refer to Formal Requirements for Planner.pdf for what endpoints are necessary.

Endpoint Map

• /degree
  • GET /?
    • returns an array of degrees matching query parameters
  • GET /:id
    • returns exact degree plan matching the databaseID
  • POST /insert
    • inserts a degree plan into the database
• /course
  • GET /?
    • returns an array of courses matching query parameters
  • GET /:id
    • returns exact course matching the databaseID
• /section
  • GET /?
    • returns an array of sections matching query parameters
  • GET /:id
    • returns exact section matching the databaseID
• /exam
  • GET /?
    • returns an array of exams matching query parameters
  • GET /:id
    • returns exact exam matching the databaseID
• /professor
  • GET /?
    • returns an array of professors matching query parameters
  • GET /:id
    • returns exact professor matching the databaseID
• /aggregate

[AdamMcAdamson]

Pretty much everything looks good to me, though I am somewhat confused on the degree plan usage.
Is this referring to course catalog degree plans? If so, shouldn't they be managed separately, as with course/section data?

Also, I'm thinking we could easily offer conditional search query parameters, simply by having them be comma separated (this may be bad practice).
i.e:

// all CS courses which are 3 or 4 credit hours.
// GET  www.example.com/course/search?credit_hours=3,4&subject_prefix=CS

// results in the query...
db.courses.find({ credit_hours: { $in : [ "3", "4" ]}, subject_prefix: "CS"})

[AdamMcAdamson]

Athena has expressed a need for aggregation for 'Professors to courses to sections' on a per-semester basis.

In order to handle data lookup and aggregation, I suggest we include an aggregate parameter:

//  In all GET routes for:
//  /degree        /professors
aggregate = "courses" | "sections"     // "sections" implies courses -> sections

// /course
aggregate = "sections"

For per-semester aggregation, a bucketed aggregation with another parameter flag would almost certainly be worth implementing:

// /professors GET
// /search       /:id 
bucket = "semester"

// in the backend:
db.professors.aggregate([
    // $match: {...}, $lookup: {...}, ...    
    $bucket: {
        groupBy: "$path.to.start_date",                    // Field to group by
            boundaries: [S20, F20, S21, F21, S22, F22],    // Boundaries for the buckets (Replace with respective start dates) 
            default: "Other",                              // Bucket id for documents which do not fall into a bucket
            output: {                                      // Output for each bucket
                "session_name": "$academic_session.name",  // (may be incorrect)
                "sections": {
                    $addFields: {}
                }
            }
        }
    }
}

[heartgg]

Regarding comma separated values, Expressjs supports having multiples of the same query parameter to automatically make an array.
For instance,
www.example.com/course/search?credit_hours=3&credit_hours=4
would result in req.query,
{ credit_hours: [ '3', '4' ] }
I'm not sure if doing this is worse practice than just sending a separate request for each, so this might need another discussion.

As for the Athena request, why can't they just query the courses and sections by professor for each academic session?

[jmyrick02]

I'm curious why a POST endpoint is necessary for degrees. I was under the impression that we would already have represented all the degrees in the database and so posting wouldn't be necessary.

I would also add endpoints for professors since they will be free-standing in the database (one for GET :id and one for GET search?)

[jpahm]

Seconding this.

[heartgg]

I agree, I don't think it's necessary. I remember it was an issue on github which I employed in the API.

[ZzRanger]

Endpoints for accessing Exam (AP/IB/CLEP) scores would be greatly appreciated. We'll need the following from the API:

• be able to get an array of Exam objects
• get information about a specific Exam object

[heartgg]

Added to the map

[jmyrick02]

I noticed we don't have any professor endpoints, but we should since professors are free-standing in the database. I have also added two endpoints to satisfy Athena's requirements.

• /professor
  • GET /search?
    • returns an array of professors matching query parameters
  • GET /:id
    • returns exact professor matching the databaseID
  • GET /:id/:course_id
    • returns an array of sections of the specified course that professor is currently teaching or has taught
  • GET /:id/:course_id/:start_date/:end_date
    • returns an array of all sections of the specified course that the professor is currently teaching or has taught that took place within the specified range of time (started at or after the :start_date and ended at or before the :end_date).

Please give feedback on my proposal. This is making me consider re-adding a Date schema for the AcademicSection object to make date comparisons easier so please also give your thoughts on that as well.

[CharlieMahana]

Regarding the /professor/:id/:course_id endpoint, I think it would make more sense to structure it such /professor/:id/courses? and /professor/:id/sections? would respectively serve as endpoints for querying related course and section data that pertain to a professor. This would enable us to allow the user to filter data using queries to fit basically whatever their needs are. For example, if I wanted a list of computer science sections taught by a professor with id 10000 since the fall of 2019, I think that /professor/10000/sections?department=CS&start-term=F19 is very intuitive. What would you guys think of doing it like this?

[heartgg]

I prefer the query structure, so I'm going to add it to the map that way for now. It can be changed later if people have objections.

[CharlieMahana]

So I actually put more thought into this, and the endpoints discussed in my previous message are completely accessory. We'd be duplicating the endpoints for course and section with a professor argument.