The following restful endpoints are available:
HandlerAll module management requests should hit /api/modulemanagement. Schema The module management schema is available at /api/schema/modulemanagement/managementrequest.xsd CreateIn order to create a module the create tag needs to be sent containing the name, modluecode, school and faculty tags.
If the operation is successful the response returns the id of the created module in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
UpdateIn order to update a module the update tag needs to be sent containing an id tag (or external id) of the module to be updated.
If the operation is successful the response returns the id of the updated module in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
DeleteIn order to delete a module the delete tag needs to be sent containing an id tag of the module to be deleted.
If the operation is successful the response returns the id of the deleted module in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
Response CodesPossible response codes are as follows:
|
HandlerAll school management requests should hit /api/schoolmanagement. Schema The school management schema is available at /api/schema/schoolmanagement/managementrequest.xsd CreateIn order to create a school the create tag needs to be sent containing the name, and faculty tags.
If the operation is successful the response returns the id of the created school in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
UpdateIn order to update a module the update tag needs to be sent containing an id tag (or external id) of the school to be updated.
If the operation is successful the response returns the id of the updated school in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
DeleteIn order to delete a module the delete tag needs to be sent containing an id tag of the school to be deleted.
If the operation is successful the response returns the id of the deleted school in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
Response CodesPossible response codes are as follows:
|
HandlerAll course management requests should hit /api/coursemanagement. Schema The course management schema is available at /api/schema/coursemanagement/managementrequest.xsd CreateIn order to create a course the create tag needs to be sent containing the name, description and school tags (ty as well if new school).
If the operation is successful the response returns the id of the created course in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
UpdateIn order to update a module the update tag needs to be sent containing an id tag of the course to be updated.
If the operation is successful the response returns the id of the updated course in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
DeleteIn order to delete a module the delete tag needs to be sent containing an id tag of the course to be deleted.
If the operation is successful the response returns the id of the deleted course in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
Response CodesPossible response codes are as follows:
|
HandlerAll faculty management requests should hit /api/facultymanagement. Schema The faculty management schema is available at /api/schema/facultymanagement/managementrequest.xsd CreateIn order to create a faculty the create tag needs to be sent containing the name.
If the operation is successful the response returns the id of the created faculty in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
UpdateIn order to update a module the update tag needs to be sent containing an id tag of the faculty to be updated.
If the operation is successful the response returns the id of the updated faculty in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
DeleteIn order to delete a faculty the delete tag needs to be sent containing an id tag of the module to be deleted.
If the operation is successful the response returns the id of the deleted faculty in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
Response CodesPossible response codes are as follows:
|
HandlerAll user management requests should hit /api/usermanagement. Schema The user management schema is available at /api/schema/usermanagement/managementrequest.xsd CreateIn order to create a user the create tag needs to be sent containing the username, surname, course and role at the minimum.
If the operation is successful the response returns the id of the created user in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
UpdateIn order to update a user the update tag needs to be sent containing an id tag of the user to be updated.
If the operation is successful the response returns the id of the updated user in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
DeleteIn order to delete a user the delete tag needs to be sent containing an id tag of the user to be deleted.
If the operation is successful the response returns the id of the deleted user in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
Response CodesPossible response codes are as follows:
Notes 1 - RolesThe only valid roles are as follows:
Students are assigned to a course, Staff emembers use the course field to assign there type. The supported staff types are as follows:
If you are looking to change a student user to a staff suer via the API (or vice-versa) then it is important to also supply the course. Notes 2 - ModulesThe current functionality of the usermanagement API is to only enrol users onto modules that have been provided in the modules element. No un-enrolment takes place. The reasoning behind this is that the usermanagement API is to be used as the initial creation/upadte of the users before the churn of an academic year starts. Once the churn starts the modulemanagement/enrol api should be used as this is more efficient at enrolling and un-enrolling users. |
HandlerAll module management requests should hit /api/modulemanagement/enrol. Schema The user enrolment schema is available at /api/schema/modulemanagement/enrolrequest.xsd EnrolIn order to enrol a user onto a module the module id, user id and user attempt must be provided (the academic session is considered to be the current session unless provided).
If the operation is successful the response returns the id of the enrolement in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 enrol requests, meaning we need to be able to identify the response to the specific request.
Un-enrolIn order to un-enrol a user onto a module the module id and user id must be provided (the academic session is considered to be the current session unless provided).
If the operation is successful the response returns the id of the enrolement in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 enrol requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
Response CodesPossible response codes are as follows:
NotesThe enrolment API only enrols users onto modules as students. |
HandlerAll assessment management requests should hit /api/assessmentmanagement. Schema The user management schema is available at /api/schema/assessmentmanagement/managementrequest.xsd CreateIn order to create an assessment the create tag needs to be sent containing the title, type, owner, session, start date, end date and modules at the minimum.
If the operation is successful the response returns the id of the created assessmentin the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns an id in the id node if applicable and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
UpdateIn order to update an assessment the update tag needs to be sent containing an id tag of the assessment to be updated.
If the operation is successful the response returns the id of the updated assessment in the id node and a message of 'OK' in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The create tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 create requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
DeleteIn order to delete a assessment the delete tag needs to be sent containing an id tag of the user to be deleted.
If the operation is successful the response returns the id of the deleted assessment in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 delete requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
ScheduleIn order to schedule an assessment the schedule tag needs to be sent containing the owner, title, duration, session and month at a minimum.
If the operation is successful the response returns the id of the scheduled assessment in the id node and a message of 'OK' in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 schedule requests, meaning we need to be able to identify the response to the specific request.
If there is an error performing the operation the response message returns a null id node and a message in the status node. The delete tags id attribute is return in order for the external system to match up its request with the response. i.e. a request might contain 100 schedule requests, meaning we need to be able to identify the response to the specific request.
Valid attributes
Response CodesPossible response codes are as follows:
|
Filter by assessmentHandlerGradebook requests for a specifc paper should hit /api/gradebook/paper/<id>.
Filter by moduleHandlerGradebook requests for a specifc module should hit /api/gradebook/module/<id>.
If there is an error performing and of the above operations the response message returns null in the id node and a message in the status node. The create tags id attribute is returned in order to match up its request with the response.
|
External system need to be provided with external id in all calls.
API clients can now be associated with an external system. It is expected only a sys admin user would not be associated with a specific external system.
XSDs for each webservice are located at /api/schema
.
Supported media types:
In order to use the web services defiend in the API you must be authenticated. Authentication is acheived via Oauth2.Rogo uses the bshaffer php library.
The steps to get an authorisation key are as follows:
Sysadmin users can add clients and specify the web services they will be authorised to use. |
Once the client has been added the external client then needs to visit the following page on Rogo. e.g.
The ‘state’ parameter is intended to preserve some state object set by the client in the Authorization request, and make it available to the client in the response. The main security reason for this is to stop Cross Site Request Forgery (XRSF). An example of this would be a hash of the session cookie or a random value stored in the server linked to the session. Client is required to login as user linked to the client account created in step 1. The logged in user will then be asked to authorise the access rights given in step 1 to the client. An authorisation token will then be generated and returned to the client, for example:
If the client verifies the ‘state’ value returned then it will reject authentication responses that were generated as the result of requests by third party attackers trying to log the user in in the background without the user’s knowledge. |
Client site then uses Authorisation code to request access token, for example the request:
Would get a response like:
The access token can then be used to access web services until expiry. The refresh token can be used to refresh Access token until expiry. From now on you can generate new access and refresh token using your current refresh token (saves you having to login an authorise again):
|
The client can then call the web services with access token in a POST request, for example:
|
The following config settings can be found in the rogo configuration screen:
cfg_enable_api | Enables or disables the API functionality |
api_oauth_access_lifetime | Stores in seconds the lifetime of an oauth access token |
api_oauth_refresh_token_lifetime | Stores in seconds the lifetime of an oauth refresh token |
api_oauth_always_issue_new_refresh_token | Enables or disables the oauth refresh token |
api_allow_superuser | Allow sys admin users to access all availbe external systems 6.5.0 onwards. |
Logging of all API requests and reponses can be enabled by added the apilogfile config item in the configuration screen via the 'apilogfile' setting Logging is only suggested for development servers as it will chew through your disk space. |
The following frameworks are used in the api code: |