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.

MSlearn.PNG

You now create the perfect Azure Blended Learning resources into your existing academic curriculum using the Microsoft Learn Catalog API (beta).

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.

 

azure4students.PNG

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

MSLearnSandbox.PNG 


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.

  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:

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

 

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.