== 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/users||get a list of users||
|| ||parameter||none||
|| ||input||none||
|| ||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||
|| ||parameter||USER_ID||
|| ||input||none||
|| ||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/users||create a user||
|| ||parameter||none||
|| ||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/users||create 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||
||DELETE||/v1/users/{id}||remove a user with 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||
||PUT||/v1/users/{id}||update a user with 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||/v1/courses||get a list of courses for current logged in user||
|| ||parameter||none||
|| ||input||none||
|| ||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||
|| ||parameter||COURSE_ID||
|| ||input||none||
|| ||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/courses||create a course||
|| ||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||
||DELETE||/v1/courses/{id}||remove a course with 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||
||PUT||/v1/courses/{id}||update a course with 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||/v1/courses/{course_id}/users||get a list of users associated within the course {course_id}||
||POST||/v1/courses{course_id}/users||associate users to the course by {course_id}||
||DELETE||/v1/courses/{course_id}/users||remove a user from the course||
|| ||parameter||COURSE_ID||
|| ||parameter||USER_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 ||

=== Groups ===

||GET||/v1/courses/{course_id}/groups||get a list of groups in course {course_id}||
|| ||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"},{"id":"GROUP_ID1","group_num":"GROUP_NUM1","group_name":"GROUP_NAME1","course_id":"COURSE_ID"}]||
|| ||status (failure)||HTTP/1.1 404 Not Found||
|| ||output (failure)||none||
||GET||/v1/courses/{course_id}/groups/id||get a group in course by group id, course_id will be ignored||
|| ||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"}||
|| ||status (failure)||HTTP/1.1 404 Not Found||
|| ||output (failure)||none||
||POST||/v1/courses/{course_id}/groups||create a group in course {course_id}||
|| ||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"}||
|| ||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||
|| ||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||
||PUT||/v1/courses/{course_id}/groups/{id}||update a group in course by group id, course_id will be ignored||
|| ||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"}||
|| ||status (failure)||HTTP/1.1 200 OK||
|| ||output (failure)||none||

=== !Groups/Users ===

||GET||/v1/groups/{group_id}/users||get a list of users associated within the group {group_id}||
||POST||/v1/groups{group_id}/users||associate users to the group by {group_id}||
||DELETE||/v1/groups/{group_id}/users/{user_id}||remove a user from the group||
|| ||parameter||GROUP_ID||
|| ||parameter||USER_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}/grades||get a list of grades in event {event_id}||
|| ||parameter||EVENT_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}||
|| ||parameter||EVENT_ID||
|| ||parameter||USER_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}/events||get a list of events in course {course_id}||
|| ||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||/v1/courses/{course_id}/events/{event_id}||get a event in course {course_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||/v1/courses/{course_id}/users/{username}/events||get events for a user in a course||
||GET||/v1/users/{username}/events||get events for a user||


* Events are read-only