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

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Tech Community.

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:

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

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.

API Response

The service may return the following HTTP status codes.

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

Response body

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

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

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

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

Module records

Each module will have the following form:

{
    "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
}

Learning path records

Each Learning path will have the following form:

{
    "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
}

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:

{
    "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:

{
    ...
    "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.

{
    ...
    "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"
        },
        ...
    ]
}