Educator Developer Blog

8 MIN READ

Using Microsoft Learn new API to enable amazing content for a blended learning curricula

Microsoft

Feb 11, 2020

You now create the perfect Azure Blended Learning resources into your existing academic curriculum using the Microsoft Learn Catalog API (beta). https://docs.microsoft.com/en-us/learn/support/catalog-api

The Microsoft Learn API lets you send a web-based query to Microsoft Learn and get back details about published content such as titles, products covered, and links to the training. an take the returned information and display the modules abd learning paths in your learning management systems (LMSs) such as Moodle, Canvas, Blackboard and WebLearn alongside other training content.

Customers can use this API to display information about the available training, but the training must be completed on Microsoft Learn. This is the perfect resource if you want to develop hands on labs, workshops, tutorials or assessments.

Student and institutions using Microsoft Office365 or AAD can utilise single sign on from their LMS to the Microsoft Learn environment and if students have activated Azure for Student they can on-click access to their Azure Subscriptions.

A number of Microsoft Learn modules include a dedicated FREE Azure Sandbox to undertake the hands on aspects of the course.

The Catalog API is offered under the terms of the Microsoft APIs Terms of Use.

The following instructions provide technical details about the API and how to interpret the information returned.

Modules and Learning Paths

Content in Microsoft Learn is organized around two elements: modules and learning paths.

Modules

A module is the actual training content. A single module consists of multiple web pages that explore a service or technology and often provide some form of interactivity to try out the technology. Each module has related metadata to quickly identify who it's for, what's covered, and how long it typically takes to complete. These details can be found in the graphical tiles on the Microsoft Learn browse page, as shown in the following screenshot.

Learning Paths

A learning path is a collection of related modules presented in a specific order so that the modules build on one another to teach a broader topic. Learning paths also include descriptive metadata similar to modules, as shown in the screenshot from the browse page below.

API endpoint

The Microsoft Learn Catalog API is a REST-based Web API that returns a JSON-encoded response.

To request the full catalog of modules and learning paths, send a GET request to:

HTML

https://docs.microsoft.com/api/learn/catalog/

Important

The request must use the HTTPS protocol.

Query parameters

The following are the query parameters that the request may include. The Required column indicates whether you must specify the parameter. You must URL encode the query parameter values.

Name	Value	Type	Required
locale	A valid locale code, for example 'en-us'. The returned metadata will be in the requested locale if available. If this parameter isn't supplied, a default of 'en-us' will be used.	string	No
clientId	A user-specified client identifier. It's recommended to use your domain name or a meaningful client name for this parameter.	string	Yes

API Response

The service may return the following HTTP status codes.

Status code	Description
200	Success. The body of the response includes the JSON-encoded data.
400	One of the query parameters is missing or not valid.
401	Unauthorized request. The clientId query parameter is missing from the URL.
404	The URL wasn't found on the server.
500	Unexpected server error.
503	The service is temporarily unavailable.

A successful response will include details about all modules and learning paths, as shown below.

Tip

It's highly recommended to cache the response and refresh the view of the data on periodic intervals rather than every time it's needed.

Response body

A successful response body will be encoded in JSON and have five sections:

JSON

{
    "modules": [ ... ],
    "learningPaths": [ ... ],
    "products": [ ... ],
    "roles": [ ... ],
    "levels": [ ... ]
}

Each array has one or more JSON-encoded objects containing data specific to that section of the response.

modules: is an array of published modules.
learningPaths: is an array of published learning paths.
levels: is an array of possible audience levels.
roles: is an array of possible job roles.
products: is an array of products and services covered in published modules.

Module records

Each module will have the following form:

JSON

{
    "summary": "<p sourcefile=\"azure/principles-cloud-computing/index.yml\" sourcestartlinenumber=\"1\" jsonPath=\"/summary\">Explore the core concepts of cloud computing and how it can help your business.</p>\n",
    "levels": [
        "beginner"
    ],
    "roles": [
        "administrator",
        "business-analyst",
        "developer"
    ],
    "products": [
        "azure",
        "azure-portal",
        "azure-resource-manager"
    ],
    "uid": "learn.principles-cloud-computing",
    "type": "module",
    "title": "Cloud Concepts - Principles of cloud computing",
    "duration_in_minutes": 62,
    "icon_url": "https://docs.microsoft.com/learn/achievements/principles-cloud-computing.svg",
    "locale": "en-us",
    "last_modified": "2018-09-24T00:00:00Z",
    "url": "https://docs.microsoft.com/en-us/learn/modules/principles-cloud-computing",
    "number_of_children": 10
}

Field	Type	Description
`summary`	string	A string that provides a short description of the module. The value is expressed as an HTML paragraph tag with the inner text being the summary.
`levels`	array of strings	Indicates how much experience in the role is necessary to understand all aspects of this module.
`roles`	array of strings	A list of the job roles that this module is relevant to.
`products`	array of strings	A list of relevant products this module covers.
`uid`	string	A unique identifier for this module - this value will be unique across all of MS Learn.
`type`	string	The type of record. The value will always be 'module'.
`title`	string	The title for the module in the locale requested, or US English as a fallback.
`duration_in_minutes`	integer	The average time this module takes to complete in minutes.
`icon_url`	string	A fully qualified URL to a 100x100 .svg or .png image that represents the module.
`locale`	string	The language this JSON data is written in. This value will be the requested locale if available, or 'en-us' if not.
`last_modified`	date	The last time this module had a major revision.
`url`	string	A fully qualified URL to the module in Microsoft Learn in the requested locale.
`number_of_children`	integer	The number of pages (units) this module has in it.

Learning path records

Each Learning path will have the following form:

JSON

{
    "summary": "<p sourcefile=\"paths/create-serverless-applications/index.yml\" sourcestartlinenumber=\"1\" jsonPath=\"/summary\">Azure Functions enable the creation of event driven, compute-on-demand systems that can be triggered by various external events. Learn how to leverage functions to execute server-side logic and build serverless architectures.</p>\n",
    "levels": [
        "beginner",
        "intermediate"
    ],
    "roles": [
        "developer",
        "solution-architect"
    ],
    "products": [
        "azure",
        "azure-portal",
        "azure-functions",
        "azure-cosmos-db",
        "azure-cloud-shell"
    ],
    "uid": "learn.create-serverless-applications",
    "type": "learningPath",
    "title": "Create serverless applications",
    "duration_in_minutes": 450,
    "icon_url": "https://docs.microsoft.com/learn/achievements/create-serverless-applications.svg",
    "locale": "en-us",
    "last_modified": "2018-12-27T00:00:00Z",
    "url": "https://docs.microsoft.com/en-us/learn/paths/create-serverless-applications",
    "modules": [
        "learn.choose-azure-service-to-integrate-and-automate-business-processes",
        "learn.create-serverless-logic-with-functions",
        "learn.execute-azure-function-with-triggers",
        "learn.chain-azure-functions-data-using-input-output-bindings",
        "learn.azure-create-long-running-serverless-workflow-with-durable-functions",
        "learn-pr.develop-test-deploy-azure-functions-core-tools",
        "learn.develop-test-deploy-azure-functions-with-visual-studio",
        "learn.azure.monitor-github-events-with-a-function-triggered-by-a-webhook",
        "learn.advocates.azure-functions-and-signalr"
    ],
    "number_of_children": 9
}

Field	Type	Description
`summary`	string	A string that provides a short description of the learning path. The value is expressed as an HTML paragraph tag with the inner text being the summary.
`levels`	array of strings	Indicates how much experience in the role is necessary to understand all aspects of this learning path. This array will contain one or more values based on the modules included in the path.
`roles`	array of strings	A list of the relevant job roles for this learning path.
`products`	array of strings	A list of relevant products this learning path covers.
`uid`	string	A unique identifier for this learning path - this value will be unique across all of MS Learn.
`type`	string	The type of record. The value will always be 'learningPath'.
`title`	string	The title for the learning path in the locale requested, or US English as a fallback.
`duration_in_minutes`	integer	The average time this learning path takes to complete in minutes. This value is a sum of data from all the modules included.
`icon_url`	string	A fully qualified URL to a 100x100 .svg or .png image that represents the learning path.
`locale`	string	The language this JSON data is written in. This value will be the requested locale if available, or 'en-us' if not.
`last_modified`	date	The last time this learning path was changed.
`url`	string	A fully qualified URL to the learning path in Microsoft Learn in the requested locale.
`modules`	array of strings	The list of module identifiers (uid's) included in this learning path.
`number_of_children`	integer	The number of modules this learning path has in it.

Product, role, and level records

The levels, roles, and products collections provide friendly names for the values used in the module and learning path data. All three collections have the same shape:

JSON

{
    "id": "unique-id",
    "name": "name-of-item",
    "children": [
        { "id": "unique-id", "name": "name-of-item" },
        { "id": "unique-id", "name": "name-of-item" },
           ...
    ]
}

The id will match the values for levels, roles, and products included in each module and learning path. The associated name provides a proper name in English for the entry. The children array is optional and enables hierarchical for values that have child relationships such as products.

As an example, here is a set of possible roles:

JSON

{
    ...
    "roles": [
        {
            "id": "administrator",
            "name": "Administrator"
        },
        {
            "id": "ai-engineer",
            "name": "AI Engineer"
        },
        {
            "id": "business-analyst",
            "name": "Business Analyst"
        },
        {
            "id": "developer",
            "name": "Developer"
        },
        ...
    ]
}

Here is an example set of products, with children included to provide a more specific product category.

JSON

{
    ...
    "products": [
        {
            "id": "dotnet",
            "name": ".NET",
            "children": [
                { "id": "dotnet-core", "name": ".NET Core" },
                { "id": "dotnet-standard", "name": ".NET Standard" },
                { "id": "aspnet-core", "name": "ASP.NET Core" },
                { "id": "ef-core", "name": "Entity Framework Core" }
            ]
        },
        {
            "id": "ms-graph",
            "name": "Microsoft Graph"
        },
        {
            "id": "office",
            "name": "Office",
            "children": [
                { "id": "office-365", "name": "Office 365" },
                { "id": "office-add-ins", "name": "Office Add-ins" },
                { "id": "office-teams", "name": "Teams" }
            ]
        },
        {
            "id": "sql-server",
            "name": "SQL Server"
        },
        ...
    ]
}