[[PageOutline(1-100,Table of Contents)]]

= 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
1. A collection (array) of JSON objects requested by client
1. 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 [#ErrorCode 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 500 Internal Server Error||
||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|| ||