Goals
Talis Aspire offers a number of APIs with which data can be retrieved from the system, and which allow changes and updates to be made. These APIs can be used by system developers to automate processes within their University, and link them into their Talis Aspire data.
This article is designed as a primer on how these can be used by developers.
Video
Here is a video version of this article with explanation and examples.
Overview
Talis Aspire has three generations of APIs available. The Open Access APIs, which we sometimes refer to as the “classic” APIs do not require any authentication, and return simple subsets of data which is publicly available.
The newer APIs, which we call the “Authenticated APIs”, subdivide into v2 and v3 versions of the API and return much richer datasets with more options available for discovery. Version 3 APIs also offer writeable routes to directly modify the data within Talis Aspire. As the name suggests, these APIs are secured behind an OAuth2 authentication layer.
These authenticated APIs are considered to be in Beta and subject to frequent change as the development of the Talis Aspire features that use these APIs is highly active. You are advised to check documentation regularly. Beta access to these APIs allows you to build ‘proof of concept’ type applications, but using these APIs in a production environment is done so at your own risk. It should be expected at this stage that there will be gaps, and that is one of the reasons that we are opening the API up to customers in a Beta capacity. Your assistance helps us identify what those gaps are.
This article will focus on the use of the new v3 Authenticated APIs, stepping through the process of authentication and making queries (and updates) in Talis Aspire. For use of our Open Access APIs, please see the following support articles.
The examples below will all use a bash-like command line, available on most linux, macOs, unix-based, and now even modern Windows10-based systems. This is a good environment to demonstrate and play with the APIs, as well as building simple scripts. It’s likely you will use a variety of other programming environments when building automated for your University based on these APIs, which is out of scope of this primer, although we do discuss some suggested tooling and libraries later on in this article.
The Canada urls are slightly different
In this article we will be giving examples using the `talis.com` urls, but for Canadian institutions all `talis.com` urls become `ca.talis.com`. So:
https://rl.talis.com becomes https://rl.ca.talis.com
https://users.talis.com becomes https://users.ca.talis.com
Documentation
All available V3 API routes can be found at https://rl.talis.com/3/docs; these docs are still in development as the APIs progress, so are currently subject to change. To quickly scan through what is available, click “Collapse” in the top-right of the page to remove the detail next to each entry. Alternatively, to drill down to read or write operations click the “get”, “insert”, or “push” buttons in the top right of an expanded individual entry to filter down to those routes only.
Authentication
Authentication takes place via OAuth2. A valid Key and Secret can be obtained from Talis by raising a support ticket.
The first step of a call to the Talis Authenticated APIs is to use your key and secret to get a token with an OAuth2 Client Credentials Grant flow. This token can then be used to authenticate API requests.
Imagine we have been given a client_id of “client_value”, and a secret of “secret_value”. To get a token from the command line, we could do the following (this command uses jq to parse the JSON):
CLIENT=’client_value’
SECRET=’secret_value’
TOKEN=$(curl -sS -u $CLIENT:$SECRET https://users.talis.com/oauth/tokens -d 'grant_type=client_credentials' | jq -r '.access_token')
This will populate the TOKEN variable locally with a token. If you’re curious, you can view this token with:
echo $TOKEN
The token can then be passed along with all calls to the API which we will look at in the next section. Please be aware that the token has a natural lifespan, currently of 1 hour, and will expire. Any tooling built to use the Talis Authenticated APIs will need to be able to detect when API calls fail to authenticate and then request a new token to continue.
API calls and responses
By now we should have a token ready to use to make API calls. If you’re not sure about this, please read the previous section on “Authentication”.
An example call to the API will look something like this:
curl -X GET \
https://rl.talis.com/3/broadminster/lists/2A1ABBD5-8673-9489-EF55-029E46EA7E4E \
-H “Authorization: Bearer ${TOKEN}” \
-H 'cache-control: no-cache'
In this call we are passing the token as a header along with a call to the endpoint requested, and receiving a json response containing the data requested. If you would like to easily read this response on the commandline it may help to pass it through a tool called jq, which will pretty-print the response, as in the following example:
curl -X GET https://rl.talis.com/3/broadminster/lists/2A1ABBD5-8673-9489-EF55-029E46EA7E4E -H "Authorization: Bearer ${TOKEN}" -H 'cache-control: no-cache' | jq
From this point you are now able to read from any available API endpoint in the Authenticated APIs.
Making a write request
Let’s try making another request to the API, but this time we are going to change the title of a list.
As before we first need to get a token using our credentials, as per the prior instructions, or if we already have a token which is still valid we can simply reuse that (Always be prepared in your code to check for an expired token, and request a new one).
Once we have a valid token we can make a call looking something like this:
curl -X PATCH \
https://rl.talis.com/3/technicaltwo/lists/2A1ABBD5-8673-9489-EF55-029E46EA7E4E \
-H 'Authorization: Bearer $TOKEN' \
-H 'X-Effective-User: IJpKy6P9uhrZJeE8ZBHdTA' \
-H 'cache-control: no-cache' \
-d '{
"data": {
"type": "lists",
"id": "2EDBAF50-0435-0292-483D-F996D23B5084",
"attributes": {
"title": "changed by API"
}
}
}'
You will notice a new header being passed here : X-Effective-User. Currently each write request to Talis Aspire occurs in the context, or on behalf of, another user, and this value identifies that user. It will be sensible to choose a meaningful user. There is no concept of a generic system user in Talis Aspire.
Subject to change: The use of X-Effective-User is under review and may be designed out of the APIs, but is currently required.
The value itself is the user’s GUID, which uniquely identifies each user in Talis Aspire. The GUID must already exist in Talis Aspire. The GUID for each user can be discovered by exporting the All User Profiles report as a CSV via the Reading Lists Reports menu, and looking in the Talis GUID column.
The data, describing the change we wish to make, is being passed as json. The structure of this json is described in the docs for each request, but for this particular request the type (lists), and the id (the UUID of the list, as seen in the list’s URL) are required attributes.
A successful response will return 200 with the updated list json as the body.
Postman
As an alternative to the CLI when trying to play with the APIs, consider trying out the Postman API development tool. It simplifies the process, allows you to store requests, and looks much nicer than a typical CLI environment.
In a new request, select the Authorization tab:
Followed by:
Now you should be confronted with a dialog to enter your API credentials. It should look as below, although substituting for your own Client ID and Client Secret:
After clicking Request Token it will go away and request a token, just as we did in our first step on the CLI, and then use that token to add an authentication header into the “Headers” tab. You don’t need to view this, but if you’re curious go ahead and click the tab to take a look.
Finally, enter the API endpoint you require into the box at the top of the screen and click “send”
The request will be made, and the response will appear at the bottom of your screen.
Tips and tricks
Hydration - Some API routes can be hydrated with additional data if required. This involves passing additional parameters which simply instruct the route to search for wider volumes of data in the database, and return it with the results. Any additional hydration of data will result in additional work for the servers to perform and will thusly slow down the response times, potentially quite noticeably in data-rich areas, so please use these with care.
An example of hydration - correct at the time of writing - would be for the /{shortCode}/lists/{listGuid} route, which can be passed the following options to add related data to the list response: include=sections,list,content,period,owners,nodes. Any type of data included under the "relationships" information in a get response can be used to hydrate the response.
ETag - To safeguard against clashing changes being made to a list at the same time (for example, if two users are attempting to edit the same list) some routes require an ETag to be passed along with the update request. The ETag is simply a hash representing a particular version of a list, and can be retrieved with any list response, either with a get request or saved from a prior update success response.
Each update will result in a new ETag, and so you will need to build your apps to send this updated ETag along with your next update request. This means that your code will need to do operations to a list sequentially.
Student Numbers - For now, we recommend avoiding any heavy work around reading or updating student numbers, as this area of the system is under review and is highly likely to change. If you want to work with Student Numbers, please have a conversation with Talis.