API In Depth
This page represents a more in depth discussion of the functionality and features introduced in the Authenticated API Documentation page.
OAuth 2.0 Overview
The UNIWeb API follows the OAuth 2.0 protocol for authentication and authorization using the Client-Credentials flow.
Users have to be enabled with the requisite permissions to access the API, once this is done access tokens can be requested according to permission settings.
After this point, resources will be accessible by essentially providing the resource path and desired actions. Responses will be returned based upon the permissions of the requestor.
This section describes the basic functionality, process and use cases that the API supports.
Setting up Authorized Clients
1. Obtain OAuth 2.0 credentials through the UNIWeb Administration Interface
In your institution's Administration Interface, a System Administrator can view, create, edit and remove OAuth 2.0 client profiles with credentials such as clientID, clientSecret, redirectURL, scope and expiration, which are used to generate an access token.
These credentials will then be associated with an access token, allowing the permissions created for the profile to be used for future resource requests.
For added security and monitoring purposes, this Authorized Profile-creation step is currently only possible through the administration interface (as opposed to passing credentials to an authorization server over the wire).
The following profile information can be set through the interface:
sourceURL | Specifies the valid source from which requests to the API should come from. Implemented to avoid some types of hijacking attacks. |
redirectURL | Responses and redirects from the authorization server will be directed towards this registered URI. Implemented to prevent some types of attacks. Ideally, the HTTP redirect URL should be protected with TLS security, using HTTPS. This functionality can help to prevent tokens from being intercepted during authorization. |
scope | Specifies a list of permissible actions that may be requested by the client. |
expiry | Specifies a custom access token expiry time (the default is one hour). |
2. Obtain an access token from the Authorization Server
Send a POST HTTP request to your token endpoint given in your Administration Interface with your credentials in the Authorization header.
"POST /api/token.php HTTP/1.1
Host: uniweb.yourinstitution.edu
Authorization: Basic username:password"You will receive a response based upon the validity of the credentials.
If the credentials are not valid, the server will return an error. Otherwise, a JSON response will be sent containing the access_token.
If you use one of the provided libraries, Step 2 and 3 are combined to simplify the management of the access token.
As per the IETF RFC describing the OAuth 2.0 protocol:
Since requests to the token endpoint result in the transmission of clear-text credentials (in the HTTP request and response), the authorization server MUST require the use of TLS (as described in Section 1.6 when sending requests to the token endpoint.
The client MUST use the HTTP "POST" method when making access token requests.
The parsed access token will be usable until the time of expiration is reached, generally this is set to a default value of one hour, but can be adjusted through the administration interface. Expiration time is given in seconds (3600 = 1 hour).
3. Use the access token to request resources
For simple read requests, send a POST HTTP request to your resource endpoint given in your Administration Interface with the access_token appended in the query string.
"POST /api/resource.php HTTP/1.1
Host: uniweb.yourinstitution.edu
access_token=1768bd20dac2e3f51789d6c24ef23866e9898e8b"For filtered read requests or insert requests, the access_token must be included in the JSON data object that is sent.
"POST /api/resource.php HTTP/1.1 Host: uniweb.yourinstitution.edu "{ "action": "read", "access_token": "1768bd20dac2e3f51789d6c24ef23866e9898e8b", "Others": "..." }
Normally, responses are sent back to the IP that requested the resource, with the contents based upon the permissions of the client that made the request. If the redirectURL is set, all responses to resource requests are sent to the URI matching the redirectURL.
Exploring the API
Due to the dynamic and client specific nature of the database, the following set of API action endpoints can be used to view the possible values for the fields that are used in structuring the JSON resource requests.
uniweb.yourinstitute.com/api/getPermissions?access_token=6jFrxo6FreYui7koc4sPiFxbqm8S6
Note: the action keywords are case-sensitive
In the example requests below, ellipsis have been used for brevity.
- getTitles
- getUnits
- getRoles
- getPermissions
- getAssignedRoles
- getRolesPermissions
- getMembers
- getSections
- getFields
| getTitles | Array of Strings representing the current Titles in your system |
| getUnits | Array of Objects representing the current Units' hierarchy in your system |
Each unit has a 'unit_id' and 'unit_name' which can be used for filtering in API queries.
Each unit also has a 'parent_unit_id' property which provides the information about the hierarchy of your institution's various units.
The top level unit would be your entire institution, whose parent_unit_id is null.
| getRoles | Array of Objects representing the current Roles in your system |
| getPermissions | Array of Objects representing the current permissions options of your system |
| getAssignedRoles | Array of Arrays representing the current Role ID, Profile, and Permission in your system |
| getRolesPermissions | Array of Objects representing the current roles and their associated permissions in your system |
| getMembers | Array of Objects representing the current members listed by id, name, unit and title in your system |
| getSections | Array of Objects representing the sections by id, parent section, reference name and label in your system |
| getSections | Array of Objects representing the sections by id, parent section, reference name and label in your system |
| getFields | Array of Objects representing the complete list of accessible information fields in your system |
