apiary.apib

FORMAT: 1A

# SCU Evals

The SCU Evals API powers the SCU Evals front-end by managing all the data and actions.

## Meta [/]

### Get API Status [GET]

+ Response 200 (application/json)
    + Attributes
        + status: ok (string, required)
            

## Authentication [/auth]

### Authenticate New/Old User [POST]

+ Request (application/json)
    + Attributes
        + id_token (string, required)

+ Response 200 (application/json)
    + Attributes
        + status: ok, new, incomplete (enum[string], required, fixed)
        + jwt (string, required)

+ Response 500 (application/json)
    + Attributes
        + message: `failed to get certificates from Google: <reason>` (string, required)

+ Response 401 (application/json)
    + Attributes
        + status: `suspended` (string, required, fixed)
        + until: `2018-03-07T12:14:04.531000+00:00` (string, required) - ISO 8601

+ Response 422 (application/json)
    + Attributes
        + message (enum[string], required, fixed-type)
            + `invalid id_token: <reason>`

+ Response 403 (application/json)
    + Attributes
        + status: `non-student` (string, required, fixed)
        

### Validate User Token [GET /auth/validate]

Validates the JWT and verifies that the permissions in it are up-to-date,
then returns a new one based on the information in the first one.

+ Response 200 (application/json)
    + Attributes
        + jwt (string, required) - New JWT


### Refresh User Token [GET /auth/refresh]

Validates the JWT and returns a new one freshly generated from the database.

+ Response 200 (application/json)
    + Attributes
        + jwt (string, required) - New JWT

### Authenticate API Key [POST /auth/api]

+ Request (application/json)
    + Attributes
        + `api_key`: `<API_KEY>` (string, required)

+ Response 200 (application/json)
    + Attributes
        + jwt (string, required)


## Classes [/classes/{quarter_id}/{professor_id}/{course_id}]

### Get Class Details [GET]

+ Parameters
    + quarter_id: 1 (number) - The ID of the quarter that the class was taught
    + professor_id: 1 (number) - The ID of the professor that taught the class
    + course_id: 1 (number) - The ID of the course that was taught

+ Response 200 (application/json)
    + Attributes
        + course (Course, required)
        + quarter (Quarter, required)
        + professor (Professor, required)
        + user_posted: false (boolean, required)
            Whether the current user has posted an 
            evaluation or not for this combination
            

+ Response 404 (application/json)
    + Attributes
        + message: class does not exist (string, required, fixed)
            

## Courses [/courses]

### List All Courses [GET /courses{?quarter_id,professor_id}]

+ Parameters
    + quarter_id (number, optional) - Limit the list to courses that were taught during the specified quarter
    + professor_id (number, optional) - Limit the list to courses that were taught by the specified professor

+ Response 200 (application/json)
    + Attributes (array[Course], fixed-type)


### List Top Courses [GET /courses/top{?count,department_id}]

+ Parameters
    + count (number, optional)
        + Default: 5
    + department_id (array[number], optional)

+ Response 200 (application/json)
    + Attributes (array, required, fixed-type)
        + (object, required)
            + course (Course, required)
            + avg_score: 3.0 (number, required)
            
+ Response 404 (application/json)
    + Attributes
        + message: `department with id <id> not found` (string, required)


### Post Courses [POST]

+ Request (application/json)
    + Attributes
        + courses (array, fixed-type)
            + (object, required)
                + term: 1 (string, required)
                + subject: ANTH (string, required)
                + catalog_nbr: 1L (string, required)
                + class_descr: Intro to Bio Anth (string, required)
                + instr_1: Doe, John (string, required)
                + instr_2 (string, required)
                + instr_3 (string, required)

+ Response 200 (application/json)
    + Attributes
        + result: success (string, fixed)
        + updated_count: 248 (number, required)

+ Response 422 (application/json)
    + Attributes
        + message (enum[string], required, fixed)
            + Members
                + `The request was well-formed but was unable to be followed due to semantic errors.`
                + missing department to COEN

### Get Course Details [GET /courses/{id}{?embed}]

+ Parameters
    + id: 1 (number) - The course for which to get details
    + embed (enum[string], optional)
        Which other data to embed. 
        Specifying `professors` gives you a list of professors that has taught the course.
        
        + Members
            + `professors`
        
    
+ Response 200 (application/json)
    
    Example response with the professors embedded.
    
    + Attributes (Course, required)
        + evaluations (array, required, fixed-type)
            + (Evaluation, required)
                + user_vote: u, d (enum[string], required)
                + user_flagged: false (boolean, required)
                + quarter_id: 1 (number, required)
                + professor (Professor, required)
                + author (required)
                    + self: false (boolean, required)
                    + majors: 1, 3 (array[number], required)
                    + graduation_year: 2020 (number, required)
        + professors (array[Professor], optional)

+ Response 404 (application/json)
    + Attributes
        + message: course with the specified id not found (string, required, fixed)


## Departments [/departments]

### List All Departments [GET]

+ Response 200 (application/json)
    + Attributes (array[Department], required, fixed-type)

### Post Departments [POST]

+ Request (application/json)
    + Attributes
        + departments (array, required, fixed-type)
            + (object)
                + value: ACTG (string, required)
                + label: `Accounting (ACTG)` (string, required)
                + school: BUS (string, required)

+ Response 200 (application/json)
    + Attributes
        + result: success (string, required, fixed)
        + updated_count: 74 (number, required)

+ Response 422 (application/json)
    + Attributes
        + message: `The request was well-formed but was unable to be followed due to semantic errors.` (string, required, fixed)


## Evaluations [/evaluations]

### List All Evaluations [GET /evaluations{?professor_id,course_id,quarter_id,embed}]

+ Parameters
    + professor_id: 1 (number, optional)
    + course_id: 1 (number, optional)
    + quarter_id: 1 (number, optional)
    + embed (array[string], optional) - Specify one or more of the following: professor, course.

+ Response 200 (application/json)
    + Attributes (array, required, fixed-type)
        + (Evaluation)
            + quarter_id: 1 (number, required)
            + professor (Professor, optional)
            + course (Course, optional)
            + user_vote: u, d (enum[string], required)
            + user_flagged: false (boolean, required)
            + author (required)
                + self: false (boolean, required)
                + majors: 1, 3 (array[number], required)
                + graduation_year: 2020 (number, required)


### List Recent Evaluations [GET /evaluations/recent{?count}]

+ Parameters
    + count (number, optional) - How many recent evaluations to return.
        + Default: 10

+ Response 200 (application/json)
    + Attributes (array, required)
        + (Evaluation, required)
            + quarter_id: 1 (number, required)
            + professor (Professor, required)
            + course (Course, required)
            + user_vote: u, d (enum[string], required)
            + user_flagged: false (boolean, required)
            + author (required)
                + self: false (boolean, required)
                + majors: 1, 3 (array[number], required)
                + graduation_year: 2020 (number, required)


### Get Evaluation Details [GET /evaluations/{id}]

+ Parameters
    + id: 1 (number, required)

+ Response 200 (application/json)

    + Attributes (Evaluation, required)

+ Response 404 (application/json)
    + Attributes
        + message: `evaluation with the specified id not found` (string, required, fixed)


### Submit Evaluation [POST]

+ Request (application/json)
    + Attributes
        + quarter_id: 1 (number, required)
        + professor_id: 1 (number, required)
        + course_id: 1 (number, required)
        + display_grad_year: false (boolean, required)
        + display_majors: true (boolean, required)
        + evaluation (EvaluationDataV1, required)

+ Response 201 (application/json)
    + Attributes
        + result: success (string, required, fixed)
        + jwt (string, required)

+ Response 422 (application/json)
    + Attributes
        + message: `invalid quarter/course/professor combination` (string, required, fixed)

+ Response 409
    + Attributes
        + message: `evaluation for this combination already exists` (string, required, fixed)

### Delete Evaluation [DELETE /evaluations/{id}]

+ Parameters
    + id: 1 (number, required)

+ Response 204 (application/json)

+ Response 404 (application/json)
    + Attributes
        + message: `evaluation with the specified id not found` (string, required, fixed)

+ Response 403 (application/json)
    + Attributes
        + message: `you are only allowed to delete your own evaluations` (string, required, fixed)


## Evaluation Votes [/evaluations/{id}/vote]

+ Parameters
    + id: 1 (number, required)

### Add/Overwrite Vote [PUT]

+ Request (application/json)
    + Attributes
        + value: u, p (enum[string], required, fixed)

+ Response 204 (application/json)

+ Response 403 (application/json)
    + Attributes
        + message: `not allowed to vote on your own evaluations` (string, required, fixed)

+ Response 404 (application/json)
    + Attributes
        + message: `evaluation with the specified id not found` (string, required, fixed).

### Delete Vote [DELETE /evaluations/{eval_id}/vote]

+ Parameters
    + eval_id: 1 (number, required)

+ Response 204 (application/json)

+ Response 404 (application/json)
    + Attributes
        + message (enum[string], required, fixed)
            + `evaluation with the specified id not found`
            + `vote not found`


## Evaluation Flags [/evaluations/{id}/flag]

+ Parameters
    + id: 1 (number, required)

### Add Flag [POST]

+ Request (application/json)
    + Attributes
        + `reason_ids`: 1, 2 (array[number], required)
        + comment: Foo (string, optional)

+ Response 201 (application/json)

+ Response 403 (application/json)
    + Attributes
        + message: `not allowed to flag your own evaluations` (string, required, fixed)

+ Response 409 (application/json)
    + Attributes
        + message: `user already flagged this evaluation` (string, required, fixed)

+ Response 422 (application/json)
    + Attributes
        + message: `no reason with id <ID> exists` (string, required, fixed)



## Majors [/majors]

### List All Majors [GET]

+ Response 200 (application/json)
    + Attributes (array[Major], required, fixed-type)

### Post Majors [POST]

+ Request (application/json)
    + Attributes
        + majors: `Sample Major 1`, `Sample Major 2` (array[string], required, fixed-type)

+ Response 200 (application/json)
    + Attributes
        + result: success (string, required, fixed)

+ Response 422 (application/json)
    + Attributes
        + message: `failed to insert majors: <db error>` (string, required)


## Official User Types [/official_user_types]

### Post Official User Types [POST]

+ Request (application/json)
    + Attributes
        + official_user_types (array, required, fixed-type)
            + (object)
                + email: jdoe@scu.edu (string, required)
                + type: `student` (string, required)

+ Response 200 (application/json)
    + Attributes
        + result: success (string, required, fixed)
        + updated_count: 1 (number, required)

+ Response 422 (application/json)
    + Attributes
        + message: `The request was well-formed but was unable to be followed due to semantic errors.` (string, required, fixed)


## Professors [/professors]

### List All Professors [GET /professors{?course_id,quarter_id}]

+ Parameters
    + course_id: 1 (number, optional) - Limit the list to professors that taught the specified course.
    + quarter_id: 1 (number, optional) - Limit the list to professors who taught during the specified quarter.

+ Response 200 (application/json)
    + Attributes (array[Professor], required, fixed-type)
    

### List Top Professors [GET /professors/top{?count,department_id}]

+ Parameters
    + count (number, optional)
        + Default: 5
    + department_id (array[number], optional)

+ Response 200 (application/json)
    + Attributes (array, required, fixed-type)
        + (object, required)
            + professor (Professor, required)
            + avg_score: 3.0 (number, required)
            
+ Response 404 (application/json)
    + Attributes
        + message: `department with id <id> not found` (string, required)


### Get Professor Details [GET /professors/{id}{?embed}]

+ Parameters
    + id: 1 (number) - The professor for which to get details.
    + embed (enum[string], optional)
        Which other data to embed.
        Specifying `courses` gives you a list of courses that this professor has taught.

        + Members
            + `courses`

+ Response 200 (application/json)

    Example response with the courses embedded.

    + Attributes (Professor, required)
        + evaluations (array, required, fixed-type)
            + (Evaluation, required)
                + user_vote: u, d (enum[string], required)
                + user_flagged: false (boolean, required)
                + quarter_id: 1 (number, required)
                + course (Course, required)
                + author (required)
                    + self: false (boolean, required)
                    + majors: 1, 3 (array[number], required)
                    + graduation_year: 2020 (number, required)
        + courses (array[Course], optional)

+ Response 404 (application/json)

    + Attributes
        + message: professor with the specified id not found (string, required, fixed)


## Quarters [/quarters{?course_id,professor_id}]

### List All Quarters [GET]

+ Parameters
    + course_id: 1 (number, optional) - Limit the list to quarters during which the specified course was taught.
    + professor_id: 1 (number, optional) - Limit the list to quarters during which the specified professor taught.

+ Response 200 (application/json)
    + Attributes (array[Quarter], required, fixed-type)


## Search [/search{?q,limit}]

+ Parameters
    + q: Mat (string, required) - The search query.
    + limit (number, optional) - Limit the number of results. Max is 50.
        + Default: 50

### Search For Classes And Professors [GET]

+ Response 200 (application/json)
    + Attributes
        + courses (array[Course], required, fixed-type)
        + professors (array[Professor], required, fixed-type)


## Student [/students/{id}]

+ Parameters
    + id: 1 (number, required)

### Update Info [PATCH]

+ Request (application/json)
    + Attributes
        + graduation_year: 2020 (number, required)
        + gender: m, f, o (enum[string], required, fixed)
        + majors: 1, 4 (array[number], required) - Between 1 and 3 major IDs.

+ Response 200 (application/json)
    + Attributes
        + result: success (string, required, fixed)
        + jwt (string, required)

+ Response 403 (application/json)
    + Attributes
        + message: `you do not have the rights to modify another student` (string, required, fixed)

+ Response 422 (application/json)
    + Attributes
        + message: `invalid major(s) specified` (string, required, fixed)


### List All Evaluations [GET /students/{id}/evaluations{?professor_id,course_id,quarter_id,embed}]

+ Parameters
    + professor_id: 1 (number, optional)
    + course_id: 1 (number, optional)
    + quarter_id: 1 (number, optional)
    + embed (array, optional)
        + (enum[string])
            + professor
            + course

+ Response 200 (application/json)
    + Attributes (array, required, fixed-type)
        + (Evaluation)
            + quarter_id: 1 (number, required)
            + professor (Professor, optional)
            + course (Course, optional)
            + user_vote: u, d (enum[string], required)
            + user_flagged: false (boolean, required)
            + author (required)
                + self: false (boolean, required)
                + majors: 1, 3 (array[number], required)
                + graduation_year: 2020 (number, required)


# Data Structures

## Course (object)
+ id: 1 (number, required)
+ number: 42 (string, required)
+ title: What is Life (string, required)
+ department_id: 3 (number, required)

## Department (object)
+ id: 1 (number, required)
+ abbr: COEN (string, required)
+ name: Computer Science & Engineering (string, required)
+ school: EGR (string, required)

## Evaluation (object)
+ id: 1 (number, required)
+ version: 1 (number, required)
+ post_time: `2018-02-06T22:24:11.098122-08:00` (string, required) - Post time in ISO 8601
+ data (EvaluationDataV1, required)
+ votes_score: `-3` (number, required)

## EvaluationDataV1 (object)
+ attitude: 1 (number, required)
+ availability: 1 (number, required)
+ clarity: 1 (number, required)
+ grading_speed: 1 (number, required)
+ resourcefulness: 1 (number, required)
+ easiness: 1 (number, required)
+ workload: 1 (number, required)
+ recommended: 1 (number, required)
+ comment: Love the lectures (string, required)

## Major (object)
+ id: 1 (number, required)
+ name: Mathematics (string, required)

## Professor (object)
+ id: 1 (number, required)
+ first_name: John (string, required)
+ last_name: Doe (string, required)

## Quarter (object)
+ id: 1 (number, required)
+ year: 2018 (number, required)
+ name: Spring (string, required)
+ period (required)
    + start: 2018-01-01 (string, required)
    + end: 2018-03-01 (string, required)

## Student (User)
+ gender: m, f, o (enum[string], required)
+ graduation_year: 2020 (number, required)
+ majors (array[number], required) - An array of majors ids

## User (object)
+ id: 1 (number, required)
+ university_id: 1 (number, required)
+ email: jdoe@scu.edu (string, required)
+ first_name: John (string, required)
+ last_name: Doe (string, required)
+ picture: https://foo.bar/d3hj2d2lk8 (string, required) - The URL to the user's picture
+ roles (array[number], required) - An array of roles ids