Enable your customers to discover and select the content they want to deliver to their team, by building your own content catalogue interface using the Learning Objects API endpoint.
Overview
This guide explores how to create your own content catalogue interface – with the purpose of surfacing the Go1 library within your application using the Learning Objects endpoint.
Building the catalogue within your application is core to how your users will discover and interact with Go1 content. There are various use-cases the content catalogue you build may support, some examples include:
- For Admins, a curation storefront for customers to discover & select the content they would like to add to your platform.
- For Learners, a direct user-facing content library, for learners to explore and enrol in self-directed learning.
The solution you build will depend on the integrated experience you are looking to create within your platform. The steps in this guide will provide you with the necessary knowledge you need to support your scenario of choice.
The benefit to building your own content catalogue interface via the API (as opposed to using the Embeddable Go1 Catalogue) is the flexibility you have to customise the user experience and interface you present to users within your application.
How it works
To surface Go1 content within your application we’ll utilize the Learning Objects endpoint.
What is a learning object?
In Go1's database, each piece of content is represented as a learning-object (often abbreviated to LO), and consists of the following metadata items:
- lo-id, an integer that acts as the unique identifier for the learning object
- title, the learning object title
- description, the learning object description
- provider, the content provider for this learning object (eg. SkillSoft)
- image, a thumbnail image representing the learning object, created by the content provider
- duration, the approximate duration of the learning object in seconds
- + many more items of metadata, click here to view the full list.
How is the learning objects endpoint used?
The Learning Objects endpoint is used to retrieve a list of Go1 content (and its associated metadata), that is returned by the API as a body of JSON. The JSON body can then be ingested by your application, and rendered to a front-end catalogue for users to view and interact within your platform.
In addition, the Learning Objects endpoint provides a rich set of features that enable consumers of the API to query the entire Go1 content library in real time by passing a series of query parameters. These parameters enable the following key use cases:
- Listing learning objects (no query parameters used) - retrieve a flat list of content for browsing.
- Keyword search - query the learning objects based on a provided keyword.
- Filter learning objects - filter the learning objects by provider, topics, duration + more.
- Sort learning objects - sort the returned set of learning objects based on a sort preference (eg. relevance, popularity, etc).
For a more comprehensive look into the functionality available via the learning-objects endpoint, see our API reference documentation. We’ll cover these features in more detail in the implementation steps below.
Implementation Steps
Step 1. List learning objects
To build a catalogue surfacing Go1 content within your application, we'll first walk through how to retrieve a list of Go1's learning objects by making a call to the Learning Objects endpoint without any query parameters. This request will return all of the learning objects the requesting Portal has access to.
Note. The learning objects endpoint can then be queried in various different ways using keyword search, filters, sorting, etc - we’ll discuss these options in greater detail in steps 2 and beyond below.
1.1. To list learning objects, make a GET request to https://api.go1.com/v2/learning-objects:
curl --location --request GET 'https://api.go1.com/v2/learning-objects' \ --header 'Authorization: Bearer <CUSTOMER_ACCESS_TOKEN>'
1.2. The response will include an array of learning objects the requesting Go1 Portal has access to, including the associated metadata for each returned LO. Below is an example with a single learning object returned:
{
"total": 84315,
"hits": [
{
"id": LO ID,
"type": "LO TYPE (EG. COURSE)",
"title": "LO TITLE",
"image": "LO IMAGE URL",
"language": "en",
"description": "LO DESCRIPTION",
"created_time": "2019-03-16T09:28:21+00:00",
"updated_time": "2020-02-06T02:47:25+00:00",
"summary": "",
"assessable": true,
"collections": [],
"portal_collection": false,
"delivery": {
"duration": 12,
"mode": "self-paced"
},
"previewable": false,
"pricing": {
"currency": "AUD",
"price": 0,
"tax": 0,
"tax_included": true
},
"provider": {
"id": PROVIDER ID,
"logo": "PROVIDER LOGO IMAGE URL",
"name": "PROVIDER NAME"
},
"subscription": {
"licenses": -1,
"package": "premium"
},
"tags": [
"Writing",
"Creative Inspiration",
"Communication Skills"
],
"attributes": {
//other attributes of the Learning Object; eg. topics, regional relevance, mobile compatibility, etc.
}
}
}Note. While the total number of learning objects available to this request is 84315 (as shown on the first line of the response above), responses to the LO endpoint are paginated and will return a default number of 20 learning objects in the array for each page. We’ll walk through how to paginate through the results in step 2 below, using the limit and offset parameters.
Step 2. Adding pagination
To paginate through the returned learning objects, the limit and offset parameters can be added to your request:
curl --location --request GET 'https://api.go1.com/v2/learning-objects?limit=50&offset=50' \ --header 'Authorization: Bearer <CUSTOMER_ACCESS_TOKEN>'
The limit parameter is used to determine the number of objects returned in each request (max 50).
The offset parameter is used to return the next page of learning objects. The offset value used in the request will determine where to start paging the next set of results that will be returned.
Examples:
- limit=50 and offset=0, will return learning objects 1-50.
- limit=50 and offset=50, will return learning objects 51-100.
Alternate pagination method: Scroll & Scroll-id
When iterating over large sets of data (ie. when you need to retrieve more than 10k records), you'll need to use the scroll and scrollid parameters instead of offset. Offset only allows you to reach a maximum of 10,000 results. To learn how to implement these parameters, see the documentation in our API Reference.
Step 3. Adding search
To add search capabilities to the Learning Objects request (and to the catalogue you build within your application), include the keyword query parameter. With this parameter, you can pass in any keywords, and the API will return a list of Learning Objects relevant to your specific keyword search:
curl --location --request GET 'https://api.go1.com/v2/learning-objects?offset=0&limit=50&keyword=leadership&sort=relevance' \ --header 'Authorization: Bearer <CUSTOMER_ACCESS_TOKEN>'
Note. When using the keyword parameter, you will also need to add the sort=relevance query to ensure that the results returned will be sorted by relevance to the keyword. We’ll discuss sorting preferences in greater detail in step 4 below.
Step 4. Adding sort preferences
Adding the sort parameter to your request allows users to specify the order in which the set of queried learning objects will be returned.
There are 4 primary sort options available:
- title - sorts result in alphabetical order based on the learning object title.
- relevance - when searching by keyword, sorts results based on our relevance algorithm.
- popularity - sorts results based on the most used content.
- created - sort results by creation date.
If no sort option is added, the library will be sorted based on title by default. For this reason, setting the correct sorting options and allowing users to select their own sorting preference is essential for providing users with the best content search and discovery experience.
When making a 'search' request by passing a keyword to /v2/learning-objects, we recommend setting the sort parameter to relevance:
curl --location --request GET 'https://api.go1.com/v2/learning-objects?keyword=leadership&sort=relevance' \ --header 'Authorization: Bearer <CUSTOMER_ACCESS_TOKEN>'
When displaying the catalogue on a blank page with no search being made, we recommend setting the sort parameter to popularity to return the most popular content first:
curl --location --request GET 'https://api.go1.com/v2/learning-objects?keyword=leadership&sort=popularity' \ --header 'Authorization: Bearer <CUSTOMER_ACCESS_TOKEN>'
Additionally, we recommend building your interface to allow end-users to select their own sort preferences. Refer to the screenshot at the top of this section for an example.
Note. you can also specify the sorting direction - eg.
- sort=created:desc will sort by creation date, showing the most recent objects first.
- sort=created:asc will sort by creation date, showing the oldest created objects first.
Step 5. Adding filters
With over 80,000 pieces of learning content in the Go1 library - it's important to enable end-users to find the content they need as quickly and as easily as possible. To assist users in discovering the most relevant content, we recommend implementing our set of filters to the Learning Objects query. You can learn how to implement these filters by visiting the Search and Discovery Filters document.
In this document, we'll introduce each of our filters, and provide implementation instructions for you to follow. We'll cover the following filters: Sort-by, Topics, Providers, Language, and Duration.
Display Go1's 'primary metadata fields' on each piece of content
When displaying Go1's content via a course card, table, catalogue or similar user interface within your application, it is recommended to always display our 'primary' set of content metadata fields for each learning object. The content metadata fields we suggest include; title, provider, duration, image, and type.
Displaying these fields allows users to easily identify content that they are looking for and that is most relevant to them within the Go1 library.
Ideas for building your own catalogue
The steps above are designed to act as an introduction to the Learning Objects API endpoint, which you can use to create your own catalogue experience within your application. Ultimately, how the catalogue is built and surfaced to users in your platform is up to you to design - this typically depends on the user experience you are looking to create. Below are a few examples of user experiences we have seen be successful in the past.
A curation storefront for Admin
The catalogue you build can be used as a tool for administrators in your platform to find and select the content they would like to import. This is particularly useful if your application has an existing course-ware object that Go1 content would need to be imported as. This is also useful to provide your customers with the choice of which content they want to provide to their organisation. To support this approach, consider adding the following features to the catalogue you build:
- Add an import state & button on each LO you display in your catalogue, allowing users to easily import content they find to your platform.
- Building on the above point, provide a mechanism for users to shortlist content and import their list in bulk.
A learning-facing content library
You might also consider building the catalogue as a way to help end-learners engage directly with learning. Providing your learners with the ability to explore and conduct self-directed learning can be a great value to an existing product offering. To support this experience, consider how you might allow users to access and play the content directly via the catalogue - see our Play Content concept which explores this further.
Learn More
To learn more about working with Go1 learning objects see the following reference links.
- Learning Objects API Reference
- Adding search suggestions (coming soon)
- Adding content previews (coming soon)
- Utilising playlists for curation and content suggestions (coming soon)