apiary.apib

FORMAT: 1A

# SWAPR API

API for the MOOC SWAPR application. REMEMBER: always authenticate and include token in the header


# Group Auth Token
Get an Authorization Token, there are three types of users: root, SWAPRInstructor, SWAPRUser (students). Yes, the root password and username is 'root', and 'root' respectively

## Token [/api-token-auth/]

### Get Token [POST]
+ Request (application/json)

        {
            "password": "root",
            "username": "root"
        }

+ Response 201 (application/json)

        {
            "token": "dfbd47cd9c5a499fd8d987b44ee064cb4e5bbfb2"
        }


# Group Instructor Creation
Creating students, will be deprecated after GT authentication provided

## Instructor Endpoint [/swaprinstructors/]

### Create SWAPRInstructor [POST]
+ Request (application/json)

        {
            "username": "teacher0",
            "first_name": "FIRSTNAME",
            "last_name": "LASTNAME",
            "email": "teacher0@email.com",
            "password": "password0"
        }

+ Response 201 (application/json)

        {
            "id": 1,
            "username": "teacher0",
            "first_name": "FIRSTNAME",
            "last_name": "LASTNAME",
            "email": "teacher0@email.com"
            "role_id": 2
        }

+ Response 400 (application/json)

        {
            "error": "unable to create new instructor"
        }

# Group User Creation
Creating students, will be deprecated after GT authenticaiton provided

## Student Endpoint [/swaprusers/]

### Create SWAPRUser [POST]
+ Request (application/json)

        {
            "username": "student0",
            "first_name": "FIRSTNAME",
            "last_name": "LASTNAME"
            "email": "student0@email.com",
            "password": "password0"
        }

+ Response 201 (application/json)

        {
            "id": 4,
            "username": "student0",
            "first_name": "FIRSTNAME",
            "last_name": "LASTNAME"
            "email": "student0@email.com"
            "role_id": 3
        }

+ Response 400 (application/json)

        {
            "error": "unable to create new user"
        }

# Group User Promotion

## Promotion Endpoint [/promote]

### Promote to SWAPRInstructor [POST]
+ Request (application/json)

        {
            "username": "student0"
        }

+ Response 201 (application/json)

        {
            "id": 4,
            "username": "student0",
            "first_name": "FIRSTNAME",
            "last_name": "LASTNAME",
            "email": "student0@email.com"
            "role_id": 2
        }

+ Response 400 (application/json)

        {
            "error": "unable to promote user"
        }

# Group Grades
Deprecated, look in assignments

## Grade [/grades/{id}]
Deprecated, look in assignments


# Group Assignments

## Assignments [/assignments]
Assignments related resources of the **SWAPR API**

### List ALL Assignments, no grades [GET]
+ Response 200 (application/json)

        [
            {
                "id": 1,
                "swaprinstructor": 1,
                "description": "submission assignment number 1 for courseNumber 1",
                "type": "submission",
                "course": 1,
                "due_date": "2014-01-02T04:56:00Z",
                "date_posted": "2015-03-16T04:52:00.108Z",
                "related_assignment": null,
                "grade": null
            },
            {
                "id": 2,
                "swaprinstructor": 1,
                "description": "evaluation assignment submission assignment number 1",
                "type": "evaluation",
                "course": 1,
                "due_date": "2014-01-02T04:56:00Z",
                "date_posted": "2015-03-16T04:52:00.108Z",
                "related_assignment": 1,
                "grade": null
            }
        ]

## Assignment [/assignments/{id}]
A single Assignment object with all its details. this DOES NOT get an video url for the student to grade

+ Parameters
    + id (required, string) ... String `id` of the assignment to retrieve.

### Retrieve an Assignment [GET]
+ Response 200 (application/json)

        {
            "id": 2,
            "swaprinstructor": 1,
            "description": "evaluation assignment submission assignment number 1",
            "type": "evaluation",
            "course": 1,
            "due_date": "2014-01-02T04:56:00Z",
            "date_posted": "2015-03-16T04:52:00.108Z",
            "related_assignment": 1,
            "items": [
                {
                    "id": 1,
                    "question": "item #1 for assignment number: 2 for class number 1 related to assignment number:1",
                    "max_value": 5,
                    "assignment": 2
                },
                {
                    "id": 2,
                    "question": "item #2 for assignment number: 2 for class number 1 related to assignment number:1",
                    "max_value": 5,
                    "assignment": 2
                },
                {
                    "id": 3,
                    "question": "item #3 for assignment number: 2 for class number 1 related to assignment number:1",
                    "max_value": 5,
                    "assignment": 2
                },
                {
                    "id": 4,
                    "question": "item #4 for assignment number: 2 for class number 1 related to assignment number:1",
                    "max_value": 5,
                    "assignment": 2
                }
            ],
            "grade": null
        }

## Create Submission Assignment [/assignments/]
make sure type is submission, regular post request

### Make Submission Assignment [POST]
+ Request (application/x-www-form-urlencoded)

        {
            "assigner": "chris wang setupscript",
            "course": 1,
            "description": "submission assignment number 1 for courseNumber 1",
            "due_date": "2014-01-02T00:00:00-04:56",
            "type": "submission"
        }

+ Response 201

        {
            "course": 1,
            "date_posted": "2015-03-16T01:01:03.775-04:00",
            "description": "submission assignment number 1 for courseNumber 1",
            "due_date": "2014-01-02T00:00:00-04:56",
            "id": 1,
            "related_assignment": [],
            "swaprinstructor": 1,
            "type": "submission"
        }


## Create Evaluation Assignment [/evalassignments/]
make sure type is evaluation! this call is JSON

### Make Evaluation Assignment [POST]
+ Request (application/json)

        {
            "course": 1,
            "description": "evaluation assignment submission assignment number 1",
            "due_date": "2014-01-02T00:00:00-04:56",
            "items": [
                {
                    "max_value": 5,
                    "question": "item #1 for assignment number: 2 for class number 1 related to assignment number:1"
                },
                {
                    "max_value": 5,
                    "question": "item #2 for assignment number: 2 for class number 1 related to assignment number:1"
                },
                {
                    "max_value": 5,
                    "question": "item #3 for assignment number: 2 for class number 1 related to assignment number:1"
                },
                {
                    "max_value": 5,
                    "question": "item #4 for assignment number: 2 for class number 1 related to assignment number:1"
                }
            ],
            "related_assignment": 1,
            "type": "evaluation"
         }

+ Response 201

        {
            "course": 1,
            "date_posted": "2015-03-16T01:09:59.096-04:00",
            "description": "evaluation assignment submission assignment number 2",
            "due_date": "2014-01-03T00:00:00-04:56",
            "id": 4,
            "related_assignment": 2,
            "swaprinstructor": 1,
            "type": "evaluation"
        }

## Submit URL
submit assignment to be graded as url

### Submit URL [POST]
+ Request (application/json)
    {
        "url": "http://example.com/xyz"
    }

+ Response 201
    {
        "url": "http://example.com/xyz"
    }

# Group getURLToGrade
get assignment meta data

## getURLToGrade [/getUrlToGrade/?assignment={assignment_id}]
Get assignment meta-data for a specific course

+ Parameters
    + id (required, string) ... String ASSIGNMENT_ID of an evaluation assignment

### retrieve assignment metadata for a course [GET]
+ Response 200 (application/json)

        {
            "url": "url for student 3 for assignment 1",
            "items": [
                {
                    "id": 1,
                    "question": "item #1 for assignment number: 2 for class number 1 related to assignment number:1",
                    "max_value": 5,
                    "assignment": 2
                },
                {
                    "id": 2,
                    "question": "item #2 for assignment number: 2 for class number 1 related to assignment number:1",
                    "max_value": 5,
                    "assignment": 2
                },
                {
                    "id": 3,
                    "question": "item #3 for assignment number: 2 for class number 1 related to assignment number:1",
                    "max_value": 5,
                    "assignment": 2
                },
                {
                    "id": 4,
                    "question": "item #4 for assignment number: 2 for class number 1 related to assignment number:1",
                    "max_value": 5,
                    "assignment": 2
                }
            ],
            "submission": 1
        }

# Group EvaluationItems
After you get a url to grade, this is how you submit your evaluations

## EvaluationItems [/evaluationItems/]
list of items that you are evaluating

### Enroll a Course [POST]

+ Request (application/x-www-form-urlencoded)

        [
            {
                "comment": "comment from chris setupscript",
                "evaluation": 1,
                "id": 1,
                "item": 1,
                "rating": 2
            },
            {
                "comment": "comment from chris setupscript",
                "evaluation": 1,
                "id": 2,
                "item": 2,
                "rating": 2
            },
            {
                "comment": "comment from chris setupscript",
                "evaluation": 1,
                "id": 3,
                "item": 3,
                "rating": 2
            },
            {
                "comment": "comment from chris setupscript",
                "evaluation": 1,
                "id": 4,
                "item": 4,
                "rating": 2
            }
        ]

+ Response 201


# Group Courses
All operations that have to do with getting grade information.

## Courses [/courses]
### List ALL Courses [GET]

+ Response 200 (application/json)

        [
            {
                "id": 1,
                "name": "course1",
                "institution": "Georgia Tech",
                "department": "Physics"
            },
            {
                "id": 2,
                "name": "course2",
                "institution": "Georgia Tech",
                "department": "Physics"
            },
            {
                "id": 3,
                "name": "course3",
                "institution": "Georgia Tech",
                "department": "Physics"
            },
            {
                "id": 4,
                "name": "course4",
                "institution": "Georgia Tech",
                "department": "Physics"
            }
        ]

### Create Course [POST]

+ Request (application/x-www-form-urlencoded)

        {
            "name": "course5",
            "institution": "Georgia Tech",
            "department": "Physics"
        }

+ Response 201 (application/json)

        {
            "id": 5,
            "name": "course5",
            "institution": "Georgia Tech",
            "department": "Physics"
        }

+ Response 400 (application/json)

        {
            "error": "new course could not be created"
        }

## Course [/courses/{id}]
A single course

+ Parameters
    + id (required, string) ... String `id` of the assignment to retrieve.

### Retrieve a Course [GET]

+ Response 200 (application/json)

        {
            "id": 5,
            "name": "course5",
            "institution": "Georgia Tech",
            "department": "Physics"
        }

+ Response 400 (application/json)

        {
            "error": "invalid course id"
        }

# Group Sessions
Operations for dealing with individual course sessions

## Course Sessions [/courses/{course_id}/sessions]

+ Parameters
    + course_id (required, string) ... String `id` of the course.

### List Sessions [GET]

+ Response 200 (application/json)

        [
            {
                "course_id": 5,
                "session_id": 1,
                "instructors": [1,2],
                "semester": "fall",
                "year": 2015,
                "status": "complete",
                "students": [4,5,6]
            },
            {
                "course_id": 5,
                "session_id": 2,
                "instructors": [1,2],
                "semester": "spring",
                "year": 2016,
                "status": "complete",
                "students": [7.8.9]
            },
            {
                "course_id": 5,
                "session_id": 3,
                "instructors": [3],
                "semester": "fall",
                "year": 2016,
                "status": "active",
                "students": [10,11,12]
            }
        ]

### Create Session [POST]

+ Request (application/x-www-form-urlencoded)

        {
            "instructors": ["teacher0"],
            "semester": "spring",
            "year": 2017,
            "status": "pending"
        }

+ Response 201 (application/json)

        {
            "course_id": 5,
            "session_id": 4,
            "instructors": [1],
            "semester": "spring",
            "year": 2017,
            "status": "pending"
        }

+ Response 400 (application/json)

        {
            "error": "new session could not be created"
        }


## Course Session [/courses/{course_id}/sessions/{session_id}]

+ Parameters
    + course_id (required, string) ... String `id` of the course.
    + session_id (required, string) ... String `id` of the session.

### Retrieve Session [GET]

+ Response 200 (application/json)

        {
            "course_id": 5,
            "session_id": 4,
            "instructors": [1],
            "semester": "spring",
            "year": 2017,
            "status": "pending",
            "students": []
        }

+ Response 400 (application/json)

        {
            "error": "invalid course or session id"
        }

### Enroll Session [POST]

+ Request (application/x-www-form-urlencoded)

        {
            "students": ["student13","student14","student15"]
        }

+ Response 201 (application/json)

        {
            "course_id": 5,
            "session_id": 4,
            "instructors": [1],
            "semester": "spring",
            "year": 2017,
            "status": "pending",
            "students": [13,14,15]
        }

+ Response 400 (application/json)

        {
            "error": "session enrollment failed"
        }