wiki:api_v1

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

Responses & Status Code

The API attempts to return appropriate HTTP status codes for every request.

Status Code:

Code Text Description
200 OK Success
201 Created Resource has been created
404 Not Found Resource is not found
500 Internal Server Error Something is broken

If querying a collection and there is nothing in the collection, an empty array will be return.

In JSON, it will be "[]".

Whenever iPeer responses a result with successful status code 2xx, the response body will always one of the following:

  1. An JSON object that requested by client
  2. A collection (array) of JSON objects requested by client
  3. An empty array "[]"

If there is an error occurred on the iPeer server side, an corresponding error status code will be returned along with the error message in the response body encoded in JSON.

{"code": 999, "message":"This is an error message"}

See details for error code.

Resources

Users

Get List of Users

GET /v1/users

Return (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"}]

Get a User with ID

GET /v1/users/{id}

parameterUSER_ID
output (success){"id":"USER0_ID","role_id":"ROLE_ID","username":"USERNAME0","last_name":"LAST_NAME","first_name":"FIRST_NAME"}

Create a User

POST /v1/users
POST Boby

{"role_id":"ROLE_ID","username":"USERNAME","last_name":"LAST_NAME","first_name":"FIRST_NAME"}
parameternone
output (success){"id":"USER_ID","role_id":"ROLE_ID","username":"USERNAME","last_name":"LAST_NAME","first_name":"FIRST_NAME"}

Create Users

POST /v1/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

Remove a user with id

DELETE /v1/users/{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

Update a user with id

PUT /v1/users/{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 a list of courses for current logged in user

GET /v1/courses

parameternone
inputnone
status (success)HTTP/1.1 200 OK
output (success)[{"id":"COURSE0_ID","course":"COURSE0_CODE","title":"COURSE0_TITLE","student_count":5},{"id":"COURSE1_ID","course":"COURSE1_CODE","title":"COURSE1_TITLE","student_count":6}]
status (failure)HTTP/1.1 404 Not Found
output (failure)No courses can be found

Get a course with id

GET /v1/courses/{id}

parameterCOURSE_ID
inputnone
status (success)HTTP/1.1 200 OK
output (success){"id":"COURSE_ID","course":"COURSE_CODE","title":"COURSE_TITLE","student_count":5}
status (failure)HTTP/1.1 404 Not Found
status (failure)No course with id COURSE_ID can be found

Create a course

POST /v1/courses

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

Remove a course with id

DELETE /v1/courses/{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

Update a course with id

PUT /v1/courses/{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 a list of users associated within the course {course_id}

GET /v1/courses/{course_id}/users

parameterCOURSE_ID
input none
status (success)HTTP/1.1 201 Created
output (success)[{"id": "1", "username":"username1", "role_id":1}, {"id": "2", "username":"username2", "role_id":1},{"id": "3", "username":"username3", "role_id":2}]
status (failure)HTTP/1.1 400 Unrecognizable Request
output (failure) none

Associate users to the course by {course_id}

POST /v1/courses{course_id}/users

parameterCOURSE_ID
input[{"username":"username1", "role_id":5}, {"username":"username2", "role_id":5},{"username":"username3", "role_id":4}], other fields in request will be ignored
status (success)HTTP/1.1 200 OK
output (success)[{"username":"username1", "role_id":5}, {"username":"username2", "role_id":5},{"username":"username3", "role_id":4}]
status (failure)HTTP/1.1 501 Unsupported role for {username}
note (failure) The role_id was unrecognized, recognized role_ids right now are student (5), tutor (4), and instructor (3)
status (failure)HTTP/1.1 501 Fail to enrol {username}
note (failure) Tried to save the new enrolments but failed due to a database error.

Remove a user from the course

DELETE /v1/courses/{course_id}/users
parameterCOURSE_ID
input[{"username":"username1", "role_id":5}, {"username":"username2", "role_id":5},{"username":"username3", "role_id":4}], other fields in request will be ignored
status (success)HTTP/1.1 200 OK
output (success)[{"username":"username1", "role_id":5}, {"username":"username2", "role_id":5},{"username":"username3", "role_id":4}]
status (failure)HTTP/1.1 501 Unsupported role for {username}
note (failure) The role_id was unrecognized, recognized role_ids right now are student (5), tutor (4), and instructor (3)
status (failure)HTTP/1.1 501 Fail to drop {username}
note (failure) Tried to save the new enrolments but failed due to a database error.

Courses/Departments

Add a course to a department

POST /v1/courses/{course_id}/departments/{department_id}

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 a course from a department

DELETE /v1/courses/{course_id}departments/{department_id}

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

Get a list of departments the user has access to

GET v1/departments

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 500 Internal Server Error
output (failure)none

Get a list of courses that belongs to the department

GET v1/departments/{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 a list of groups in course {course_id}

GET /v1/courses/{course_id}/groups

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","member_count":5},{"id":"GROUP_ID1","group_num":"GROUP_NUM1","group_name":"GROUP_NAME1","course_id":"COURSE_ID","member_count":5}], or [] if there is no group
status (failure)HTTP/1.1 500 Internal Error
output (failure)none

Get a group in course by group id, course_id will be ignored

GET /v1/courses/{course_id}/groups/id

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","member_count":5}
status (failure)HTTP/1.1 404 Not Found
output (failure)none

Create a group in course {course_id}

POST /v1/courses/{course_id}/groups

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","member_count":0}
status (failure)HTTP/1.1 500 Internal Server Error
output (failure)none

Remove a group in course by group id, course_id will be ignored

DELETE /v1/courses/{course_id}/groups/{id}

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

Update a group in course by group id, course_id will be ignored

PUT /v1/courses/{course_id}/groups/{id}

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","member_count":5}
status (failure)HTTP/1.1 200 OK
output (failure)none

Groups/Users

Get a list of users associated within the group {group_id}

GET /v1/groups/{group_id}/users

parameterGROUP_ID
inputnone
status (success)HTTP/1.1 200 OK
output (success)[{"id":"5","role_id":"5","username":"111111","last_name":"Student","first_name":"Ed"},{"id":"6","role_id":"5","username":"222222","last_name":"Student","first_name":"Alex"}]
status (failure)HTTP/1.1 400 Bad Request
output (failure)none

Associate users to the group by {group_id}

POST /v1/groups/{group_id}/users

parameterGROUP_ID
input[{"username":"111111"},{"username":"222222"}]
status (success)HTTP/1.1 200 OK
output (success, same users as input)[{"username":"111111"},{"username":"222222"}]
status (failure)HTTP/1.1 500 Internal Server Error
output (failure, return users that were successfully saved)[{"username":"111111"},{"username":"222222"}]

Remove a user from the group

DELETE /v1/groups/{group_id}/users/{user_id}

parameterGROUP_ID
parameterUSER_ID
status (success)HTTP/1.1 204 No Content
output (success)none
status (failure)HTTP/1.1 500 Internal Server Error
output (failure) none

Grades

Get a list of grades in event {event_id}

GET /v1/events/{event_id}/grades

parameterEVENT_ID
status (success)HTTP/1.1 200 OK
output (success)[{"evaluatee":"EVALUATEE_ID","score":"SCORE","username":"USERNAME"},{"evaluatee":"EVALUATEE_ID","score":"SCORE","username":"USERNAME"}]
status (failure, no results returned)HTTP/1.1 404 Not Found
status (failure, not HTTP GET request)HTTP/1.1 400 Bad Request
output (failure)none

Get a grades for a user with {username} in the event {event_id}

GET /v1/events/{event_id}/grades/{username}

parameterEVENT_ID
parameterUSERNAME
status (success)HTTP/1.1 200 OK
output (success){"evaluatee":"USER_ID","score":"SCORE","username":"USERNAME"}
status (failure, no results returned)HTTP/1.1 404 Not Found
status (failure, not HTTP GET request)HTTP/1.1 400 Bad Request
output (failure)none
  • Grades are read-only

Events

Get a list of events in course {course_id}

GET /v1/courses/{course_id}/events

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 a event in course {course_id}

GET /v1/courses/{course_id}/events/{event_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 events for a user in a course

GET /v1/courses/{course_id}/users/{username}/events

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 events for a user

GET /v1/users/{username}/events

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

Error Code

An error code is used when an API failed to execute. The code and a short message is returned instead of the result.

Category Code MessageNote
User 100
Course 200
Group 300Failed to create group! May contain additional information
User/Course 400Unsupported role
401Fail to enrol
Last modified 3 years ago Last modified on 2014-01-31T17:15:13-08:00