wiki:api_v1

Version 29 (modified by Pan Luo, 12 years ago) ( diff )

--

Overview

This is the first version of API. The main purpose of this version of API is to provide a way for external applications, e.g., learning management system, to interact with iPeer with tighter integration and better user experience. Data returned will be in JSON format with XML support coming later.

Authentication

OAuth 1.0a

Resources

Users

GET/v1/usersget a list of users
parameternone
inputnone
status (success)HTTP/1.1 200 OK
output (success)[{"id":"USER0_ID","role_id":"ROLE_ID","username":"USERNAME0","last_name":"LAST_NAME","first_name":"FIRST_NAME"},{"id":"USER1_ID","role_id":"ROLE_ID","username":"USERNAME1","last_name":"LAST_NAME","first_name":"FIRST_NAME"}]
status (failure)HTTP/1.1 404 Not Found
output (failure)none
GET/v1/users/{id}get a user with id
parameterUSER_ID
inputnone
status (success)HTTP/1.1 200 OK
output (success){"id":"USER0_ID","role_id":"ROLE_ID","username":"USERNAME0","last_name":"LAST_NAME","first_name":"FIRST_NAME"}
status (failure)HTTP/1.1 404 Not Found
output (failure)none
POST/v1/userscreate a user
parameternone
input{"role_id":"ROLE_ID","username":"USERNAME","last_name":"LAST_NAME","first_name":"FIRST_NAME"}
status (success)HTTP/1.1 201 CREATED
output (success){"id":"USER_ID","role_id":"ROLE_ID","username":"USERNAME","last_name":"LAST_NAME","first_name":"FIRST_NAME"}
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none
POST/v1/userscreate users
parameternone
input{"role_id":"ROLE_ID","username":"USERNAME0","last_name":"LAST_NAME","first_name":"FIRST_NAME"},{"role_id":"ROLE_ID","username":"USERNAME1","last_name":"LAST_NAME","first_name":"FIRST_NAME"}
status (success)HTTP/1.1 201 CREATED
output (success){"id":"USER0_ID","role_id":"ROLE_ID","username":"USERNAME0","last_name":"LAST_NAME","first_name":"FIRST_NAME"},{"id":"USER1_ID","role_id":"ROLE_ID","username":"USERNAME1","last_name":"LAST_NAME","first_name":"FIRST_NAME"}
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none
DELETE/v1/users/{id}remove a user with id
parameterUSER_ID
inputnone
status (success)HTTP/1.1 204 No Content
output (success)none
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none
PUT/v1/users/{id}update a user with id
parameterCOURSE_ID
input{"id":"USER_ID","username":"USERNAME","last_name":"LAST_NAME","first_name":"FIRST_NAME","role_id":"ROLE_ID"}
status (success)HTTP/1.1 200 OK
output (success){"id":"USER_ID","username":"USERNAME","last_name":"LAST_NAME","first_name":"FIRST_NAME","role_id":"ROLE_ID"}
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none

Courses

GET/v1/coursesget a list of courses for current logged in user
parameternone
inputnone
status (success)HTTP/1.1 200 OK
output (success)[{"id":"COURSE0_ID","course":"COURSE0_CODE","title":"COURSE0_TITLE"},{"id":"COURSE1_ID","course":"COURSE1_CODE","title":"COURSE1_TITLE"}]
status (failure)HTTP/1.1 404 Not Found
output (failure)No courses can be found
GET/v1/courses/{id}get a course with id
parameterCOURSE_ID
inputnone
status (success)HTTP/1.1 200 OK
output (success){"id":"COURSE_ID","course":"COURSE_CODE","title":"COURSE_TITLE"}
status (failure)HTTP/1.1 404 Not Found
status (failure)No course with id COURSE_ID can be found
POST/v1/coursescreate a course
parameternone
input{"Course":{"course":"COURSE_CODE","title":"COURSE_TITLE"},"Department":{"Department":[DEPARTMENT_ID]}}
status (success)HTTP/1.1 201 Created
output (success)COURSE_ID
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)Error: the course was not added
DELETE/v1/courses/{id}remove a course with id
parameterCOURSE_ID
inputnone
status (success)HTTP/1.1 204 No Content
output (success)COURSE_ID
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)Error: the course was not deleted
PUT/v1/courses/{id}update a course with id
parameternone
input{"Course":{"id":"COURSE_ID","course":"COURSE_CODE","title":"COURSE_TITLE"}}
status (success)HTTP/1.1 200 OK
output (success)COURSE_ID
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)Error: the course was not edited

Courses/Users

GET/v1/courses/{course_id}/usersget a list of users associated within the course {course_id}
POST/v1/courses{course_id}/usersassociate users to the course by {course_id}
parameterCOURSE_ID
input[{"username":"username1", "role_id":1}, {"username":"username2", "role_id":1},{"username":"username3", "role_id":2}], other fields in request will be ignored
status (success)HTTP/1.1 201 Created
output (success)[{"username":"username1", "role_id":1}, {"username":"username2", "role_id":1},{"username":"username3", "role_id":2}]
status (failure)HTTP/1.1 500 Internal Server Error
output (failure) none
DELETE/v1/courses/{course_id}/usersremove a user from the course
parameterCOURSE_ID
parameterUSER_ID
status (success)HTTP/1.1 204 No Content
output (success)none
status (failure)HTTP/1.1 500 users were not deleted
output (failure) none

Courses/Departments

POST/v1/courses/{course_id}/departments/{department_id}add a course to a department
parameterDEPARTMENT_ID
parameterCOURSE_ID
status (success)HTTP/1.1 201 Created
output (success){"course_id":"COURSE_ID", "department_id":"DEPARTMENT_ID"}
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none
DELETE/v1/courses/{course_id}departments/{department_id}/delete a course from a department
parameterDEPARTMENT_ID
parameterCOURSE_ID
status (success)HTTP/1.1 204 No Content
output (success)none
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none

Departments

GETv1/departmentsget a list of departments the user has access to
parameternone
status (success)HTTP/1.1 200 OK
output (success)[{"id":"DEPT_ID0","name":"DEPT_NAME0"},{"id":"DEPT_ID1","name":"DEPT_NAME1"}]
status (failure)HTTP/1.1 404 Not Found
output (failure)none
GETv1/departments/{department_id}gets a list of courses that belongs to the department with DEPARTMENT_ID
parameterDEPARTMENT_ID
status (success)HTTP/1.1 200 OK
output (success)[{"id":"COURSE0_ID","course":"COURSE0_CODE","title":"COURSE0_TITLE"},{"id":"COURSE1_ID","course":"COURSE1_CODE","title":"COURSE1_TITLE"}]
status (failure)HTTP/1.1 404 Not Found
output (failure)none

Groups

GET/v1/courses/{course_id}/groupsget a list of groups in course {course_id}
parameterCOURSE_ID
inputnone
status (success)HTTP/1.1 200 OK
output (success)[{"id":"GROUP_IDO","group_num":"GROUP_NUM0","group_name":"GROUP_NAME0","course_id":"COURSE_ID"},{"id":"GROUP_ID1","group_num":"GROUP_NUM1","group_name":"GROUP_NAME1","course_id":"COURSE_ID"}], or [] if there is no group
status (failure)HTTP/1.1 500 Internal Error
output (failure)none
GET/v1/courses/{course_id}/groups/idget a group in course by group id, course_id will be ignored
parameterCOURSE_ID
parameterGROUP_ID
status (success)HTTP/1.1 200 OK
output (success){"id":"GROUP_ID","group_num":"GROUP_NUM","group_name":"GROUP_NAME","course_id":"COURSE_ID"}
status (failure)HTTP/1.1 404 Not Found
output (failure)none
POST/v1/courses/{course_id}/groupscreate a group in course {course_id}
parameterCOURSE_ID
input{"group_num":"GROUP_NUM","group_name":"GROUP_NAME","course_id":"COURSE_ID"}
status (success)HTTP/1.1 201 Created
output (success){"id":"GROUP_ID","group_num":"GROUP_NUM","group_name":"GROUP_NAME","course_id":"COURSE_ID"}
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none
DELETE/v1/courses/{course_id}/groups/{id}remove a group in course by group id, course_id will be ignored
parameterCOURSE_ID
parameterGROUP_ID
status (success)HTTP/1.1 204 No Content
output (success)none
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none
PUT/v1/courses/{course_id}/groups/{id}update a group in course by group id, course_id will be ignored
parameterCOURSE_ID
parameterGROUP_ID
input{"id":"GROUP_ID","course_id":"COURSE_ID","group_num":"GROUP_NUM","group_name":"GROUP_NAME"}
status (success)HTTP/1.1 200 OK
output (success){"id":"GROUP_ID","group_num":"GROUP_NUM","group_name":"GROUP_NAME","course_id":"COURSE_ID"}
status (failure)HTTP/1.1 200 OK
output (failure)none

Groups/Users

GET/v1/groups/{group_id}/usersget a list of users associated within the group {group_id}
POST/v1/groups{group_id}/usersassociate users to the group by {group_id}
DELETE/v1/groups/{group_id}/users/{user_id}remove a user from the group
parameterGROUP_ID
parameterUSER_ID
status (success)HTTP/1.1 204 No Content
output (success)none
status (failure)HTTP/1.1 500 users were not deleted
output (failure) none

Grades

GET/v1/events/{event_id}/gradesget a list of grades in event {event_id}
parameterEVENT_ID
status (success)HTTP/1.1 200 OK
output (success)[{"evaluatee":"EVALUATEE_ID","score":"SCORE"},{"evaluatee":"EVALUATEE_ID","score":"SCORE"}]
status (failure)HTTP/1.1 404 Not Found
output (failure)none
GET/v1/events/{event_id}/grades/{user_id}get a grades for a user with {user_id} in the event {event_id}
parameterEVENT_ID
parameterUSER_ID
status (success)HTTP/1.1 200 OK
output (success){"evaluatee":"USER_ID","score":"SCORE"}
status (failure)HTTP/1.1 404 Not Found
output (failure)none
  • Grades are read-only

Events

GET/v1/courses/{course_id}/eventsget a list of events in course {course_id}
parameterCOURSE_ID
status (success)HTTP/1.1 200 OK
output (success)[{"title":"TITLE0","course_id":"COURSE_ID","event_template_type_id":"TEMPLATE_ID","id":"EVENT_ID0"},{"title":"TITLE1","course_id":"COURSE_ID","event_template_type_id":"TEMPLATE_ID","id":"EVENT_ID1"}]
status (failure)HTTP/1.1 Not Found
output (failure)none
GET/v1/courses/{course_id}/events/{event_id}get a event in course {course_id}
parameterCOURSE_ID
parameterEVENT_ID
status (success)HTTP/1.1 200 OK
output (success){"title":"TITLE","course_id":"COURSE_ID","event_template_type_id":"TEMPLATE_ID","id":"EVENT_ID"}
status (failure)HTTP/1.1 404 Not Found
output (failure)none
GET/v1/courses/{course_id}/users/{username}/eventsget events for a user in a course
parameterCOURSE_ID
parameterUSERNAME
status (success)HTTP/1.1 200 OK
output (success)[{"title":"TITLE0","course_id":"COURSE_ID","event_template_type_id":"TEMPLATE_ID","id":"EVENT_ID0"},{"title":"TITLE1","course_id":"COURSE_ID","event_template_type_id":"TEMPLATE_ID","id":"EVENT_ID1"}]
status (failure)HTTP/1.1 404 Not Found
output (failure)none
GET/v1/users/{username}/eventsget events for a user
parameterUSERNAME
status (success)HTTP/1.1 200 OK
output (success)[{"title":"TITLE0","course_id":"COURSE_ID","event_template_type_id":"TEMPLATE_ID","id":"EVENT_ID0"},{"title":"TITLE1","course_id":"COURSE_ID","event_template_type_id":"TEMPLATE_ID","id":"EVENT_ID1"}]
status (failure)HTTP/1.1 404 Not Found
output (failure)none
  • Events are read-only
Note: See TracWiki for help on using the wiki.