This guide is the tenth in a new series of new guides brought to you by
Check out Brian’s Community Coaching Session on the API Browser on-demand!
After some conversations about the API Browser and the API Quick Grabs series, a related topic of value came to light. To be clear, this installment will not be walking you through formatting data and doing an API call. Instead, this guide is designed to ‘teach you to fish’ so to speak. While many get comfortable enough in the browser to do single calls to get work done, sometimes it can be confusing where to go in the browser to do what you wish to do.
The categories below will not be comprehensive, and I imagine this document will grow over time. Below I have gathered some of commonly used endpoints I have been asked about.
Important Note: As always, it is preferable to carry out unfamiliar actions in a sandbox or training environment if available. If you do not have this option, it is best to work with test data rather than production data directly.
Guide Table of Contents
Different Types of Calls
Remember there are different types of of API endpoints you can make calls to. In the API Browser, you are doing one of 4 actions:
- GET – These are harmless as you are only viewing existing data. You cannot change or delete anything on accident using this type of call.
- POST – This call has low potential for issues as you are creating new data. You are not impacting existing data, so typically this is OK, but be careful (especially with any bulk action).
- PUT – This call is medium to high risk as you are updating data. If you do not have a sandbox environment, it is highly recommended to backup your data for safety. A report or even a screenshot of the data will be invaluable if the endpoint does not behave as you expected.
- DELETE – This is the highest of risks, you are deleting data. It will be gone, no trash bin, just gone. Only use these if you are 100% confident in what you are doing, and even then, please make a backup.
With that being said, I like to make calls to GET endpoints when I am exploring the API Browser, figuring out the difference between similar sections, and making sure I am in the right area. It gives me data that I can view and analyze to see if the section is relevant to what I’m looking for.
Before We Begin
Alright, time to dig into some topics. Just a note on documentation for the rest of this article: The API Browser has 3 layers of navigation. For the purposes of this article, I will refer to them as the following:
- Services Menu – The dropdown menu in the top left corner which broadly categorizes the API endpoints.
- API Reference Categories – These are listed on the left-hand side of the screen from top to bottom within each service menu item.
- API Endpoints – Each ‘API Reference Category’ opens to show sub-items. These are the API endpoints themselves and what you are generally trying to get to. You make ‘calls’ to the endpoints.
Throughout the article, these will be conveyed in each section in the following format:
| Services Menu > API Reference Category > API Endpoint | Description |
Enrollments
Enrollments are kind of all over the place. I’ve decided to note them here, as I think it is useful to keep these bundled together.
Learning Plans
| learn > lp > Enroll single user in Learning plan | These endpoints will let you add/remove a user from a learning plan. These are for single users. |
| learn > lp > Unenrolls a user from a learning plan | |
| learn > Enrollment > Un - Enroll users in course/s | This will allow you to bulk remove users from learning plans. |
| learningplan > Retrieve all the enrollments from learning plans | These are good to view enrollments in both the learning plan itself and the courses within the learning plan. For other actions, you will need to go elsewhere. |
| learningplan > Retrieves learning plan courses enrollments |
Courses
| learn > Course > Get enrollment report for a given course | These two are useful for viewing enrollments. The first gives all the enrollments of a specific course, while the second gives the full details of an individual user’s enrollment in a specific course. |
| learn > Enrollment > View information for enrolled user on current course | |
| learn > Enrollment > Un - Enroll user in course | These are the endpoints that let you remove, add, and update enrollments in courses for individual users. For bulk operations, see the next grouping. |
| learn > Enrollment > Update enrollment of user to course | |
| learn > Enrollment > Enroll user/s in course/s | |
| learn > Enrollment > Un - Enroll users in course/s | These are endpoints that will let you remove, add, and update enrollments in courses for multiple users at the same time. |
| learn > Enrollment > Batch unenroll of users from courses and sessions | |
| learn > Enrollment > Update enrollment of users to courses | |
| learn > Enrollment > Batch import Enrollments |
Enrollment Fields
| manage > Enrollmentfield | You can enter values into enrollment fields while enrolling a user with the above endpoints, but these endpoints does something else. The endpoints in this section will let you create, update, remove, and view data about the fields themselves. |
Archiving Enrollments
| enrollment > CoursesArchive | These are a new set of endpoints. While for other enrollment tasks there are different areas, all of the currently available archiving actions (creating and viewing them) are here. |
| enrollment > UsersArchive |
User Management
General User Calls
| manage > User | All the API endpoints related to users can be found here. Create, update, delete, add to branches, view lists of users using filters, view a specific user, etc. can all be done from within this area. |
User Additional Fields
| manage > Userfield | While you can view and update the data within a user additional field using the APIs above, this endpoint works differently. This is where you can see, add, remove, and update user additional fields themselves. |
Branches
| manage > Orgchart | This set of API endpoints will let you manage the actual branches and their structure, as well as assign users to them. It’s important to understand that because branches have levels to them and the API will present them in a flat way, you must pay attention to a few terms:
|
Groups
| audiences > Audience | Managing groups is a common request when discussing APIs. There are two sets of these currently, one named Groups (manage > Group), which seems like the right place, but don’t be fooled. These are old APIs and are being deprecated. You will also be disappointed if you try to use them, as certain information is not available through them. Instead, use the ‘audiences’ area of the services menu. There is a whole list of endpoints available in here for managing your groups. |
Content
Channels
| manage > Channels | View and update channels using these APIs. |
Catalog
| learn > Catalogue | These sets will have all the APIs to manage catalogs and the content within them. |
| learn > CatalogContent |
Central Repository
| manage > Centralrepo | View category information and information on items already imported into the repository. |
Learning Objects
| learn > lo | APIs to view and manage learning objects within courses throughout your platform. |
Courses
There are several areas that address courses. While this has been getting better over time, make sure to check them all for the best fit for your task. Keep an eye out for deprecated/outdated endpoints which will be clearly marked in their descriptions.
General Course
| learn > Course | This set is most useful when dealing with the course ‘shells’. These will let you view, edit, create, and delete courses individually and in bulk. |
| course > Courses |
Sessions
| course > Sessions | This set is for viewing, adding, updating, and removing sessions within an ILT course. |
Events
| course > Events | This set is for viewing, adding, updating, and removing events within a session within an ILT course. |
Wrap-up
The above endpoints encompass both the most requested ones I have run into and some that are harder to find in the API browser. Hopefully this helps you orient yourself and find your way around a little better.
Please use the comments below to call out any topics overlooked or you are curious about!
More API Browser Quick Grabs:
Bulk Update Course information
Bulk Unenroll Users from Courses or Learning Plans
Bulk Update User’s Enrollment to a Completion
Bulk Enroll and Mark User Complete in a Course
