Best practices for using the Microsoft Learn Catalog API
This article describes the best practices for using the Learn Catalog API.
Understand the Terms of Service
Although the Learn Catalog API is publicly available and free to use, users are subject to the Microsoft API Terms of Use. Read and understand the API Terms of Use before using the Learn Catalog API as well as before including the output in any production environment.
Understand the limitations of the Learn Catalog API
See Limitations in the Learn Catalog API Feature overview article.
Understand the Learn content model
In order to use the Learn Catalog API response effectively, it’s important to understand the types of content available in Microsoft Learn and their relationships to one another. Review the Learn content model article for more information.
Notably:
- UID stands for “Unique ID” and is unique for each content object. If a UID changes, even if the title or other metadata stays the same, the content is considered a new object.
- Modules are the core object within the Learn training catalog. They're all capable of standing alone, in the sense that they teach a scenario or concept end-to-end within them and don't require taking prerequisite modules. For some, this is it and they aren't a part of a learning path. For others, they're bundled together in one or more learning paths that take a user through building more advanced concepts. A module doesn't have to be a part of a learning path, or it can be a part of one or more.
- Units aren't written as standalone content. They're intended to be taken in a specific order for the module. For this reason, we include the link to the module detail page and the first unit so that users can start there and proceed through the content.
Understand how localization works in Learn and how localized content is reflected in the API output
Microsoft Learn supports over 65 locales on the site and much of the content has been translated into these locales. We aim to make the content available in all the languages that the product(s) being taught in the content is available in, but not all locale experiences have translated content available.
When a locale record doesn't have the associated translation available, the content on the site and the API response “falls back” to English as the default. In the case of the API output, you'll see English metadata in other locale responses when fall back happens. However, the URL to the content will still point to the locale, even though the main content may fall back and the reason is to allow the user to still navigate the site in that locale (which will show the header/footer translated, and any other link that has translation available).
When updates are published to the English content, our localization pipelines work to get the localized versions updated as soon as possible – usually within a few days of the original change.
You can see a full list of supported locales in the Microsoft Learn site footer (select on the language you're viewing). Each of these locales can be queried with the Learn Catalog API using the locale filter.
Our training content completion records are locale-agnostic, meaning, we don't differentiate localized versions of content as separate objects in our user training completion records. No matter what language a user completes a training in, they'll receive credit for the overall object, and we don't store a reference to what language it was completed in. This locale-agnostic completion means if you implement the Learn Catalog API in your learning experience, you'll need to take it into account and, if you load the content objects in as separate objects, implement an equivalency between them so that no matter which language the user completes the training in, they'll get credit for it in the other languages and not have to retake it.
Understand how content versioning works in Learn and how it's reflected in the API output
Notably, content is being updated all the time. We publish updates typically twice a day. They may either be minor, such as minor text changes, or major, such as major revisions, additions, or deletions. In general, the content portfolio is managed as a massive, highly governed open-source project with thousands of contributors, and as such, changes are happening all the time. If you use the Learn Catalog API in your production system, you should be aware of this and have your system able to handle it.
When new content objects are added, they'll appear as a new object (identified by UID) in the response. When content is modified, you can tell based on its last_modified value. When content is deleted, it will be removed from the response. Although there's sometimes a slight delay on content being updated in the API response, when a user follows the URL to the content, they'll always see the most current information. In the case of deletions, the old URL will redirect to the new content or experience.
There are no references to content versions at this time beyond the last_modified date.
Refresh the data regularly
If you're using the catalog information from the Learn Catalog API to support your business processes, or displaying for customers as a part of your site experience, make sure that you refresh the content at least once a day.
Notably, content is being updated all the time. We publish updates typically twice a day. They may either be minor, such as minor text changes, or major, such as major revisions, additions, or deletions. In general, the content portfolio is managed as a massive, highly governed open-source project with thousands of contributors, and as such, changes are happening all the time. If you use the Learn Catalog API in your production system, you should be aware of this and have your system able to handle it.
Review the recommendations the developer documentation
The Learn Catalog API developer documentation has a full list of the data provided as a part of the response, and recommendations on how each field is recommended to be used to support great learning experiences.
Understand the query logic
There are many filters available to use to pre-filter the response, so that you only get what you’re looking for and can handle smaller file sizes. You can see the full list of query filters in the Learn Catalog API Developer reference article. Notably, you'll need to form the query correctly and if you’re using more than one query parameter in the request, the query will be assessed using the AND operator.
Next steps
For more information to support you with the Learn Catalog API, review the following articles: