api_v1 – iPeer

Context Navigation

Version 30 (modified by michael, 12 years ago) ( diff )
Match Course/Users to implementation.

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}
	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
POST	/v1/courses{course_id}/users	associate users to the course by {course_id}
	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.
DELETE	/v1/courses/{course_id}/users	remove a user from the course
	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

POST	/v1/courses/{course_id}/departments/{department_id}	add a course to a department
	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	/v1/courses/{course_id}departments/{department_id}/	delete a course from a department
	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	v1/departments	get a list of departments the user has access to
	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	v1/departments/{department_id}	gets a list of courses that belongs to the department with 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	/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"}], or [] if there is no group
	status (failure)	HTTP/1.1 500 Internal Error
	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
	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	/v1/users/{username}/events	get events for a user
	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

Note: See TracWiki for help on using the wiki.

Download in other formats:

Plain Text