API Documentation - mangoapp/backend GitHub Wiki

###Login & Authentication

URI Action Body Result Response
/v1/auth Post email, password Logs in user JWT Auth Token
/v1/users Post firstname,lastname,email,password Creates new user Auth Token
/v1/passwordResetRequest Post email Emails password reset token "success", or error message
/v1/passwordResetResponse Post email,token,password Updates user email given "success", or error message
/v1/users/edit Post firstname,lastname,email,password Updates current user login New Auth Token
Note that all API calls outside of the authentication section must have the Auth token provided as a url parameter named "token". The Auth token is returned on a successful login request.

###Course Management

URI Action Body Result Response
/v1/courses Post name,section_name,type Creates new course and section with the type and names given. Type must exist in the types table "success", or error message
/v1/courses/sections Post course_id,section_name Creates new section for the specified course. "success" or error
/v1/sections Post section_id Deletes the specified section. "success" or error
/v1/users/sections Get Array of sections the user is enrolled in with associated courses/roles
/v1/users/sections Post email,sectionid Invites user to course. Logged in user must have permission. "success", or error message
/v1/users/sections/accept Post token Accepts a section invite, adds user to section "success", or error message
/v1/sections/{section_id}/students Get List of students in given section
/v1/users/roles/edit Post section_id,user_id,role_id Updates the given users role "success" or error
/v1/users/roles/kick Post section_id,user_id Kicks given user from section "success" or error

###Announcements Announcements are made to a particular section, not a course. Any user enrolled within the section can view the announcements, but only a TA or instructor can create a new announcement.

URI Action Body Result Response
/v1/announcements Post title,body, sectionID Creates new announcement with the provided paramaters "success", or error message
/v1/announcements/{section_id} Get Array of announcements for the specified section, or error message
/v1/announcements/edit Post sectionID,announcement_id Edits the corresponding announcement "success" or error message
/v1/announcements/delete Post sectionID,announcement_id Deletes the corresponding announcement "success" or error message

###Assignments Announcements are specific to each section. Each assignment can optionally have a deadline. Deadlines should be provided in the format "Y-m-d H:i", for example "2016-01-11 7:58". Body attributes with a * are optional.

If the quiz attribute is set to true, then the quiz data should be provided as json.

URI Action Body Result Response
/v1/sections/{section_id}/assignments Get Array of announcements for the specified section
/v1/sections/{section_id}/assignments Post title,description,filesubmission(boolean),quiz(boolean),*data(json),category_id, *deadline Creates specified assignment "success", or error message
/v1/sections/{section_id}/updateAssignment Post title,description,filesubmission(boolean),quiz(boolean),*data(json),category_id, *deadline Updates specified assignment "success", or error message
/v1/sections/{section_id}/deleteAssignment Post id Deletes specified quiz "success", or error message
/v1/sections/assignments/{assignment_id} GET Gets the quiz data for the given assignment

###Grades Each assignment can have a grade entry for each student in the assignment's section. Each grade must be assigned a category. A default category worth 100% of the class is created for each section automatically; However, if a new category is created for that section the default category will become worth 0%.

The quiz data should be in the format [0,1,2], where the numbers represent the id of the multiple choice selection.

URI Action Body Result Response
/v1/sections/{section_id}/grades Get Returns grades for the current user in the specified section
/v1/assignments/{assignment_id}/grades Get Returns all grades for all user for specified assignment
/v1/assignments/{assignment_id}/grades Post score, user_id Creates a grade for the assignment/user given "success" or error message
/v1/assignments/{assignment_id}/updateGrade Post score, user_id Updates the grade for the given grade entry or creates it if it doesnt exist "success" or error message
/v1/assignments/{assignment_id}/deleteGrade Post grade_id Deletes the grade for the given grade entry "success" or error message
/v1/sections/{section_id}/myAverage GET Gets the current users average grade
/v1/sections/{section_id}/users/{userId}/currentAverage GET Gets the specified users average grade. Requires instructor permissions.
/v1/sections/{section_id}/allAverages GET Gets average grade for all users in section. Requires instructor permissions.
/v1/sections/{section_id}/submitQuiz POST assignment_id, answers Submits the given quiz "success" or error message

###Grade Categories Each section can have multiple grade categories. These are useful for weighting or organizing assignments. All sections have a default category which can not be deleted or updated. Changing which assignments are in which categories is done through the Assignment endpoints, not the category endpoints.

URI Action Body Result Response
/v1/sections/{section_id}/categories Get Returns categories for the given section
/v1/sections/{section_id}/categories/{category_id}/assignments Get Returns assignments inside this category
v1/sections/{section_id}/categories Post name,weight Creates given category "success" or error message
v1/sections/{section_id}/updateCategory Post id, name,weight Updates given category "success" or error message
v1/sections/{section_id}/deleteCategory Post id Deletes given category "success" or error message

###Forum Each course has its own forum space, but we still need to send the section ID that the user is in for authentication purposes.

URI Action Body Result Response
/v1/forum/{section_id}/threads Get Returns all threads in a course forum space
/v1/forum/{section_id}/threads/{thread_id}/posts Get Returns all posts in a thread
v1/forum/threads Post section_id,title,body,anonymous,sticky Creates a thread "success" or error message
v1/forum/threads/update Post section_id,thread_id,title,body,anonymous,sticky Updates a thread given a thread_id "success" or error message
v1/forum/threads/delete Post section_id,thread_id Deletes given thread "success" or error message
v1/forum/threads/lock Post section_id,thread_id Locks given thread "success" or error message
v1/forum/threads/unlock Post section_id,thread_id Unlocks given thread "success" or error message
v1/forum/threads/sticky Post section_id,thread_id Sticky given thread "success" or error message
v1/forum/threads/unsticky Post section_id,thread_id Unsticky given thread "success" or error message
v1/forum/posts Post section_id,thread_id,body,anonymous,reply_id Posts a comment to a thread_id "success" or error message
v1/forum/posts/update Post section_id,post_id,body,anonymous Updates given post "success" or error message
v1/forum/posts/delete Post section_id,post_id Deletes given post "success" or error message
v1/forum/like Post section_id,post_id Likes given post "success" or error message
v1/forum/unlike Post section_id,post_id Unlikes given post "success" or error message
v1/forum/numLike Post section_id,post_id Total score for given post score or error message

###Notifications Each course has its own forum space, but we still need to send the section ID that the user is in for authentication purposes.

URI Action Body Result Response
/v1/notifications Get Returns all unread notifications for hte logged in user
/v1/notifications Post id Marks the specified notification as read "success" or error message

###Assignment File Submissions If an assignment has file submission enabled, students may upload files to be graded by their instructor. Files must be in pdf format to be accept by the server. If the deadline for the assignment as passed, no files may be submitted. If students submit a file for the same assignment twice, the new file will replace the old one.

In order to view a file, the logged in user must be the owner of the file or the instructor for that class.

URI Action Body Result Response
/v1/assignments/{assignment_id}/upload Post file Uploads the given file to the server "success" or error message
/v1/assignments/{assignment_id}/uploads Get Returns all submitted files for an assignment
/v1/assignments/{assignment_id}/checkUpload Get Returns the submitted file, or "no_file_submitted"
/v1/files/{file_id} Get Returns the file with the given id.

###Course Content Instructors may choose to upload documents to sections they control. This will allow any students in the section to view and download those documents. Course Content uploads work similarly to assignment file uploads. As before, only PDF documents are allowed.

URI Action Body Result Response
/v1/sections/{section_id}/upload Post file Uploads the given file to the server "success" or error message
/v1/sections/{section_id}/uploads Get Returns all course content files
/v1/sections/files/{file_id} Get Returns the file with the given id.
/v1/sections/files/{file_id}/delete Post Deletes the given file. Requires TA permissions. "success" or error message.

###Polls Instructors may choose to create in-class polls for their students to take. This is useful for taking attendance or giving in-class quizzes. Polls are created as closed by default. Responses may only be submitted while the poll is open.

URI Action Body Result Response
/v1/sections/polls Post answer,section_id,description Creates a new poll "success" or error message.
/v1/sections/polls/update Post poll_id,answer,section_id,description Updates the given poll "success" or error message.
/v1/sections/polls/delete Post poll_id Creates the given poll "success" or error message.
/v1/sections/{section_id}/polls Get Returns all polls in the section, even closed polls
/v1/sections/{section_id}/activePolls Get Returns all currently active polls in the section
/v1/sections/polls/{poll_id}/openPoll Post Opens the given poll for responses "success" or error message.
/v1/sections/polls/{poll_id}/closePoll Post Closes the given poll for responses "success" or error message.
/v1/sections/polls/{poll_id}/submitResponse Post answer Submits the response given "success" or error message.
/v1/sections/polls/1/responses Get Gets a list of responses their users for the poll

###Search Students or instructors can make use of the unified search feature to quickly look up assignments, threads, and announcements.

URI Action Body Result Response
/v1/sections/{section_id}/search/{search_query} Get Search result data

###Events Instructors may create events that show up on the course calendar, and will also show up on student's calendars.

URI Action Body Result Response
/v1/sections/{section_id}/events Get Gets all events in a section "success" or error message.
/v1/users/events Get Gets all events a user is subscribed to "success" or error message.
/v1/sections/events/create Post title, description, begin (unix timestamp), end (unix timestamp), section_id Creates the given event "success" or error message.
/v1/sections/events/update Post title, description, begin (unix timestamp), end (unix timestamp), section_id, event_id Updates the given event "success" or error message.
/v1/sections/events/delete Post title, description, begin (unix timestamp), end (unix timestamp), section_id, event_id Updates the given event "success" or error message.
/v1/calendar/{uuid} Get Get iCal given a user UUID (in JWT) "success" or error message.
/v1/calendar/section/{id} Get Get iCal given a section id "success" or error message.