<section id="introduction" >
<h2>Overview</h2><p>The purpose of the API is to integrate UNIWeb with other systems within your organization. The Authenticated API provides secure read/write access to information stored by UNIWeb, and it provides a mechanism to reduce the need to duplicate data.</p><p>The UNIWeb API provides:</p><ul class="disc-list"><li>An interface that allows you to control who has access to your institution's data through our API.</li><li>A means by which to securely read and update your institution's information.</li><li>Rich data in simple, straightforward JSON for maximum readability and reusability.</li><li>The choice to pre-filter the requested data, to obtain just the subset of information in which you are interested.</li></ul><p></p><p>The UNIWeb API uses <a href="http://www.ietf.org/" target="_blank">Internet Engineering Task Force (IETF)</a> open authentication standard <a href="http://oauth.net/2/" target="_blank">OAuth 2.0</a>, for authentication and authorization using the <a href="http://tools.ietf.org/html/rfc6749#section-4.3" target="_blank">Resource Owner Password Credentials Grant protocol</a>. In this protocol, only users with granted permission can access the API.</p><p>The following four steps are required to access a resource through API:</p><ol class="num-list"><li>Get permission to create OAuth 2.0 Clients</li><li>Create a OAuth 2.0 client and obtain client credentials</li><li>Use your Oauth 2.0 client credentials to <a href="http://tools.ietf.org/html/rfc6749#section-4.3.2" target="_blank">retrieve an access token</a>.</li><li><a href="http://tools.ietf.org/html/rfc6749#section-7" target="_blank">Use your access token</a> to interact with the API. Your token is valid for an hour from the time it is issued.</li></ol><p>These steps are explained in more details below.</p><h3>Setting up Authorized Clients</h3><h4>1. Get permission to create OAuth 2.0 Clients</h4><div class="indent"><p>A <i>System Administrator</i>, can grant any user permission to <i>create OAuth 2.0 clients</i>. If you are not the <i>System Administrator</i> yourself, ask the <i>System Administrator</i> to give you this permission, as example below shows: </p><img src="http://uniweb.network/clients/Proximify/uniweb/published/img/apiImgs/admin_rbac.png" id="rbac"/><p>Example above shows <i>Access Control</i> page, accessible from <i>Administration</i> panel, to <i>John Doe</i>, the <i>System Administrator</i>. In this example, role <i>Health Science IT Administrator</i> has the permission to <i>create OAuth 2.0 clients</i> for <i>Health Sciences</i> department. <i>John Doe</i> assigns this role to <i>Jane Roe</i>. <i>Jane Roe</i> can now <i>create OAuth 2.0 clients</i>.</p></div><h4>2. Create a OAuth 2.0 client and obtain client credentials</h4><div class="indent"><p>Using the UNIWeb Interface, you can create, edit, view and remove OAuth 2.0 clients. Each client has a unique username referred to as <i>Client ID</i>, and a system generated random password, referred to as <i>Client Secret</i>. Example below shows <i>Jane Roes</i>'s <i>OAuth 2.0 Administration</i> page.</p><img src="http://uniweb.network/clients/Proximify/uniweb/published/img/apiImgs/api_oauth.png" id="oauth"></img><p>In this example, <i>Jane Roe</i> has created two OAuth 2.0 clients. Clicking on the <i>view</i> button for <i>Alice</i> reveals her <i>Client Secret</i> as shown below:</p><img src="http://uniweb.network/clients/Proximify/uniweb/published/img/apiImgs/api_oauth-view_client.png" id="oauth-view"></img><p>In this hypothetical case, <i>Alice</i>'s <i>Client ID</i> is <i>Alice</i> and her <i>Client Secret</i> is <i>7740731b32440350fccd</i>. These credentials are used in the next step to authenticate <i>Alice</i>.</p></div><h4>3. Authenticate and get an Access Token</h4><div class="indent"><p>With the client credentials obtained in step 3, you can authenticate to the UNIWeb <i>Token Endpoint</i>, and get an <i>Access Token</i>. An <i>Access Token</i> is valid for one hour, and it will be used in the next step to retrieve resources from UNIWeb <i>Resource Endpoint</i>.</p><p>With these pieces of information you will be allowed to make API requests. To do so, you can use one of our pre-built client libraries</p><ul><li><a href="https://github.com/Proximify/uniweb-api/tree/master/clients/PHP">PHP client lib</a> (see <a href="https://github.com/Proximify/uniweb-api/tree/master/clients/PHP/examples">examples</a>)</li></ul></div><h4>4. Access information through structured requests</h4><div class="indent"><p>API requests are made by submitting JSON objects to the server. They tell the server which action, resources, sections and fields are desired and what filters to apply. In particular, the request objects can have the following properties: <strong>action</strong>, <strong>content</strong>, <strong>filter</strong>, and <strong>resource</strong>.</p><p>Example request object:</p></div><pre class="Widget JsonCode prettyprint prettyprinted"><span class="pln">{</span>
<span class="pln">"action":</span> <span class="str">"read"</span><span class="pln">,</span>
<span class="pln">"content":</span> <span class="str">"members"</span><span class="pln">,</span>
<span class="pln">"filter":</span> <span class="pln">{</span>
<span class="pln">"login":</span> <span class="str">"[email protected]"</span>
<span class="pln">}</span><span class="pln">,</span>
<span class="pln">"resource":</span> <span class="pln">[</span>
<span class="str">"profile/biography"</span><span class="pln">,</span>
<span class="str">"profile/selected_degrees"</span>
<span class="pln">]</span>
}
Example response for the above request:
{ "[email protected]": { "profile/biography": "Bob always knew he would be a great scientist", "profile/selected_degrees": [ { "degree_name": "PhD", "organization": "McGill University", "specialty": "Materials Engineering" }, { "degree_name": "Engineering", "organization": "University of Ottawa" } ] } }
<section id="requests" >
<h2>API Requests</h2><p>Before requesting information from UNIWeb, it is necessary to understand the terminology used to identify pieces of data stored in the system. The information within a UNIWeb page is usually divided into sections, sub-sections, sub-subsections and so on. A <em>section</em> contains a list of <em>items</em>. An item within a section is made out <em>fields</em>. An API <em>request</em> is the mechanism for obtaining the <em>field values</em> of all items within a section.</p><h3 id="resource_paths">Resource Paths</h3><p>In UNIWeb, a resource is always associated to a type of <em>content</em>. Current content types are: 'members', 'units' and 'groups'.</p><p>To request a resource, it is necessary to provide a path to it within UNIWeb. A <em>request path</em> can be specified as a string by separating each element in the path with '/'. The path must have the following form:</p></br><p class="centered"><code>page/section/section/section/...</code></p></br><div class="indent"><table class="Widget Table api-actions"><tbody><tr><td><code>page</code><div id="action-options" class="Togglable"></div></td><td>The 'page' where the information is displayed within UNIWeb. For example, 'profile', 'cv' or 'graph'.<div id="action-options" class="Togglable"></div></td></tr><tr><td><code>section/...</code><div id="action-options" class="Togglable"></div></td><td>Sequence of section, subsection, sub-subsection,... that contain the target set of items to retrieve.<div id="action-options" class="Togglable"></div></td></tr></tbody></table></div><span>For example, the string </span><span><pre class="InlineCode">cv/education/degrees</pre> refers to all the items within the section <em>Degrees</em>, which is a subsection of the <em>Education</em> section in the CV page of UNIWeb <em>members</em>.</span><p>Optionally, a request path can be specified as a JSON object. In particular, this is needed if one desires to request only a subset of the field values of an item. In this case, the <em>resource path</em> can be given as </p><pre> {"page/section/section/section/...": ["field name A", "field name B", ...]}</pre><p></p><p>It is also possible to encode the entire path as a JSON object. This is useful when requesting multiple sections under a common parent section or page:</p><pre> "page":{
"parent_section":[
"child_section A",
"child_section B"
]
}
The resource path above is equivalent to specifying two separate resource paths as strings:
[ "page/parent_section/child_section A", "page/parent_section/child_section B" ]
The names of sections and fields used by the API are derived from the English titles of their respective sections and fields shown in the UNIWeb UI. Spaces, slashes and question marks are not allowed in resource names. In addition, resource names are always lowercased. To "normalize" a string to meet API rules, do the following:
- Lowercase the given string
- Replace the substrings " / ", "/", and " " with ""
- Replace the substrings "?" with the empty string ""
For example, the string "Postal / Zip Code" is normalized to "postal_zip_code".
The names of sections in resource paths must: (1) correspond to the sections names shown in the UNIWeb UI, and (2) be normalized according to the API naming rules described above. For example, the path to the Address resource in a CV is written as
cv/personal_information/address
The names of fields in resource paths must: (1) correspond to the field labels in the UNIWeb UI, and (2) be normalized according to the API naming rules described above. For example, the fields shown below in the Address section can be requested as
["address_type", "address-_line_1", "location", "postal_zip_code"]
API requests are given as JSON objects with one or more of the following properties.
token | required The hashed value returned by the authorization server. | ||||||||||||||||||||||||||
action | required A string value specifying the desired action to take.
| ||||||||||||||||||||||||||
content | required Selects the type of content to retrieve.Show optionsHide options
| ||||||||||||||||||||||||||
resource | required One or more paths to the requested resources.Show optionsHide options
| ||||||||||||||||||||||||||
filter | optional An object value with filering settings.Show optionsHide options
| ||||||||||||||||||||||||||
index_by | optional Selects how the response indexed the resources in the answer.Show optionsHide options
| ||||||||||||||||||||||||||
language | optional Responses use the default institution's language unless specified otherwise.Show optionsHide options
|
<section id="examples" >
<h2>Example Requests</h2><h4>Simple Single Resource Read Request</h4><p>The request that follows would return the public profile information of all people in the Department of Civil Engineering as JSON.</p><pre class="Widget JsonCode prettyprint prettyprinted"><span class="pln">{</span>
<span class="pln">"token":</span> <span class="str">"access token"</span><span class="pln">,</span>
<span class="pln">"action":</span> <span class="str">"read"</span><span class="pln">,</span>
<span class="pln">"content":</span> <span class="str">"members"</span><span class="pln">,</span>
<span class="pln">"filter":</span> <span class="pln">{</span>
<span class="pln">"unit":</span> <span class="str">"Civil Engineering"</span>
<span class="pln">}</span><span class="pln">,</span>
<span class="pln">"resource":</span> <span class="str">"profile"</span>
}
The request that follows would return two resources belonging to the user with login name [email protected], which include:
- the publicly available research interest tags found on his Profile
- the Degree Name, Specialization, and Thesis Title fields from his CV found under Education > Degrees
{ "token": "access token", "action": "read", "content": "members", "language": "fr", "filter": { "unit": "McGill", "title": "Professor", "login": "[email protected]" }, "resource": [ "profile/research_interests", { "cv/education/degrees": [ "degree_name", "specialization", "thesis_title" ] } ] }
<section id="errors" >
<h2>Error Messages</h2><p>Errors will give information about what went wrong with a corresponding request. They will be of the following form:</p><pre class="Widget JsonCode prettyprint prettyprinted"><span class="pln">{</span>
<span class="pln">"error":</span> <span class="pln">{</span>
<span class="pln">"message":</span> <span class="str">"Error validating access token."</span><span class="pln">,</span>
<span class="pln">"type":</span> <span class="str">"OAuthException"</span><span class="pln">,</span>
<span class="pln">"code":</span> <span class="lit">98</span><span class="pln">,</span>
<span class="pln">"error_subcode":</span> <span class="lit">223</span>
<span class="pln">}</span>
}
</div>