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}

parameter	USER_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"}

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

Create Users

POST /v1/users

parameter	none
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}

parameter	USER_ID
input	none
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}

parameter	COURSE_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

parameter	none
input	none
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}

parameter	COURSE_ID
input	none
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

parameter	none
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}

parameter	COURSE_ID
input	none
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}

parameter	none
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

parameter	COURSE_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

parameter	COURSE_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

parameter	COURSE_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}

parameter	DEPARTMENT_ID
parameter	COURSE_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}

parameter	DEPARTMENT_ID
parameter	COURSE_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

parameter	none
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

Get a list of courses that belongs to the department

GET v1/departments/{department_id}

parameter	DEPARTMENT_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

parameter	COURSE_ID
input	none
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

parameter	COURSE_ID
parameter	GROUP_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

parameter	COURSE_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}

parameter	COURSE_ID
parameter	GROUP_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}

parameter	COURSE_ID
parameter	GROUP_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

parameter	GROUP_ID
input	none
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

parameter	GROUP_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}

parameter	GROUP_ID
parameter	USER_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

parameter	EVENT_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}

parameter	EVENT_ID
parameter	USERNAME
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

parameter	COURSE_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}

parameter	COURSE_ID
parameter	EVENT_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

parameter	COURSE_ID
parameter	USERNAME
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

parameter	USERNAME
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	Message	Note
User	100
Course	200
Group	300	Failed to create group!	May contain additional information
User/Course	400	Unsupported role
	401	Fail to enrol