Comhroinn trí

Quickstart: Set up and use the Microsoft Learn Platform API Catalog Data

In this Quickstart, you learn how to set up and run the Microsoft Learn Platform API, which includes examples to retrieve courses, learning paths, modules, and certifications.

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (version 18.0.0 or higher)

    • Node.js is a JavaScript runtime that allows you to run JavaScript/TypeScript code outside of a web browser. It's required to execute the example scripts and manage packages via npm (Node Package Manager).
    • Download from: https://nodejs.org/
    • Verify installation: node --version

  • Azure CLI

    • The Azure Command-Line Interface (CLI) is a tool for managing Azure resources from the command line. In this guide, it's used to authenticate your identity so the examples can access the Learn Platform API on your behalf.
    • Download from: /cli/azure/install-azure-cli
    • Verify installation: az --version

  • An Azure Account

    • An Azure account with an active subscription is required to authenticate and access the Microsoft Learn Platform API. The API uses Microsoft Entra ID (formerly Azure Active Directory) for authentication, which requires valid Azure credentials. There is no cost to retrieve the authentication token from your Azure subscription.
    • You need an active Azure subscription
    • Sign up at: https://azure.microsoft.com/free/

  • Visual Studio Code (optional)

    • Visual Studio Code (VS code) is a free, lightweight code editor with an integrated terminal, IntelliSense, and TypeScript support. While you can use any text editor and terminal, Visual Studio Code provides a streamlined experience for running these examples.
    • Download from: https://code.visualstudio.com/
    • Verify installation: Open Visual Studio Code and press Ctrl+` to open the integrated terminal

Note

All commands written below should be run in a Git Bash terminal. You can use VS Code's integrated terminal (press Ctrl+`), Windows PowerShell, or Command Prompt.

Set up the project

Follow these steps to create a new project and install the required dependencies.

  1. Create a new folder for your project and navigate to it.

    mkdir learn-api-examples
cd learn-api-examples

  2. Initialize a new Node.js project with default settings. The -y flag automatically accepts all defaults.

    npm init -y

  3. Install the required npm packages (@azure/identity for authentication, tsx to run TypeScript directly, typescript compiler, and @types/node for type definitions).

    npm install @azure/identity tsx typescript @types/node

  4. Create a new file called examples.ts and paste the code below. This includes authentication leveraging Azure Default Credentials and several examples of the catalog capabilities available through the Learn Platform API.

    /**
 * Microsoft Learn Platform API Examples
 * API Version: 2023-11-01-preview
 * Base URL: https://learn.microsoft.com/api/v1
 *
 * Authentication: OAuth2 with scope https://learn.microsoft.com/.default
 */

import { DefaultAzureCredential } from "@azure/identity";

const API_BASE_URL = "https://learn.microsoft.com/api/v1";
const API_VERSION = "2023-11-01-preview";

// ============================================================================
// AUTHENTICATION HELPER
// ============================================================================

async function getAccessToken(): Promise<string> {
  const credential = new DefaultAzureCredential();
  const token = await credential.getToken("https://learn.microsoft.com/.default");
  return token.token;
}

/**
 * Helper to handle API response with error checking
 */
async function handleResponse(response: Response, label: string): Promise<void> {
  if (!response.ok) {
    const text = await response.text();
    console.log(`${label} Error: ${response.status} ${response.statusText}`);
    console.log("Response:", text || "(empty)");
    return;
  }

  const text = await response.text();
  if (!text) {
    console.log(`${label}: (empty response)`);
    return;
  }

  try {
    const data = JSON.parse(text);
    console.log(`${label}:`, JSON.stringify(data, null, 2));
  } catch (e) {
    console.log(`${label} Parse Error: Invalid JSON`);
    console.log("Raw response:", text.substring(0, 500));
  }
}

// ============================================================================
// TRAINING ENDPOINTS
// ============================================================================

/**
 * List all courses with optional filters
 * GET /courses
 */
async function listCourses(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/courses?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Courses");
}

/**
 * Get a specific course by ID
 * GET /courses/{id}
 */
async function getCourse(courseId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/courses/${courseId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Course");
}

/**
 * List all learning paths
 * GET /learning-paths
 */
async function listLearningPaths(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  subjects?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.subjects) params.append("subjects", options.subjects.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/learning-paths?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Learning Paths");
}

/**
 * Get a specific learning path by ID
 * GET /learning-paths/{id}
 */
async function getLearningPath(learningPathId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/learning-paths/${learningPathId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Learning Path");
}

/**
 * List all modules
 * GET /modules
 */
async function listModules(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  subjects?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.subjects) params.append("subjects", options.subjects.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/modules?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Modules");
}

/**
 * Get a specific module by ID
 * GET /modules/{id}
 */
async function getModule(moduleId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/modules/${moduleId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Module");
}

/**
 * Get a specific unit by ID
 * GET /units/{id}
 */
async function getUnit(unitId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/units/${unitId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Unit");
}

// ============================================================================
// CREDENTIALS ENDPOINTS
// ============================================================================

/**
 * List all certifications
 * GET /certifications
 */
async function listCertifications(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  subjects?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.subjects) params.append("subjects", options.subjects.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/certifications?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Certifications");
}

/**
 * Get a specific certification by ID
 * GET /certifications/{id}
 */
async function getCertification(certificationId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/certifications/${certificationId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Certification");
}

/**
 * List all exams
 * GET /exams
 */
async function listExams(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/exams?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Exams");
}

/**
 * Get a specific exam by ID
 * GET /exams/{id}
 */
async function getExam(examId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/exams/${examId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Exam");
}

/**
 * List all applied skills
 * GET /applied-skills
 */
async function listAppliedSkills(options?: {
  levels?: string[];
  roles?: string[];
  products?: string[];
  subjects?: string[];
  locale?: string;
  maxpagesize?: number;
}): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (options?.levels) params.append("levels", options.levels.join(","));
  if (options?.roles) params.append("roles", options.roles.join(","));
  if (options?.products) params.append("products", options.products.join(","));
  if (options?.subjects) params.append("subjects", options.subjects.join(","));
  if (options?.locale) params.append("locale", options.locale);
  if (options?.maxpagesize) params.append("maxpagesize", options.maxpagesize.toString());

  const response = await fetch(`${API_BASE_URL}/applied-skills?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Applied Skills");
}

/**
 * Get a specific applied skill by ID
 * GET /applied-skills/{id}
 */
async function getAppliedSkill(appliedSkillId: string, locale?: string): Promise<void> {
  const token = await getAccessToken();

  const params = new URLSearchParams({ "api-version": API_VERSION });
  if (locale) params.append("locale", locale);

  const response = await fetch(`${API_BASE_URL}/applied-skills/${appliedSkillId}?${params}`, {
    method: "GET",
    headers: {
      "Accept": "application/json",
      "Authorization": `Bearer ${token}`
    }
  });

  await handleResponse(response, "Applied Skill");
}

// ============================================================================
// PAGINATION HELPER
// ============================================================================

/**
 * Helper to handle paginated responses
 */
async function fetchAllPages<T>(initialUrl: string, token: string): Promise<T[]> {
  const allItems: T[] = [];
  let nextLink: string | undefined = initialUrl;

  while (nextLink) {
    const response = await fetch(nextLink, {
      method: "GET",
      headers: {
        "Accept": "application/json",
        "Authorization": `Bearer ${token}`
      }
    });

    const data = await response.json();
    allItems.push(...data.value);
    nextLink = data.nextLink;
  }

  return allItems;
}

// ============================================================================
// EXAMPLE USAGE
// ============================================================================

async function main() {
  try {
    // List beginner-level certifications for Azure
    console.log("=== Listing Azure certifications (beginner level) ===");
    await listCertifications({
      levels: ["beginner"],
      products: ["azure"],
      maxpagesize: 5
    });

    // List certifications
    console.log("\n=== Listing certifications ===");
    await listCertifications({ maxpagesize: 5 });

    // List all Spanish learning paths
    console.log("\n=== Listing Spanish learning paths ===");
    await listLearningPaths({ locale: "es-es", maxpagesize: 5 });

    // Get a specific learning path by ID
    console.log("\n=== Getting learning path: learn.introduction-ai-azure ===");
    await getLearningPath("learn.introduction-ai-azure");

    // Get a specific module by ID
    console.log("\n=== Getting module: learn.wwl.fundamentals-generative-ai ===");
    await getModule("learn.wwl.fundamentals-generative-ai");

    // Get a specific unit by ID
    console.log("\n=== Getting unit: learn.wwl.fundamentals-generative-ai.agents ===");
    await getUnit("learn.wwl.fundamentals-generative-ai.agents");

    // Get a specific applied skill by ID
    console.log("\n=== Getting applied skill: applied-skill.deploy-and-configure-azure-monitor ===");
    await getAppliedSkill("applied-skill.deploy-and-configure-azure-monitor");

    // Get a specific certification by ID
    console.log("\n=== Getting certification: certification.d365-functional-consultant-customer-service ===");
    await getCertification("certification.d365-functional-consultant-customer-service");

    // Get a specific exam by ID
    console.log("\n=== Getting exam: exam.77-881 ===");
    await getExam("exam.77-881");

    // Get a specific instructor-led course by ID
    console.log("\n=== Getting instructor-led course: course.ai-900t00 ===");
    await getCourse("course.ai-900t00");

  } catch (error) {
    console.error("Error:", error);
  }
}

main();

Authenticate and run the examples

Follow these steps to authenticate with Azure and run the example code.

  1. Sign in to Azure CLI. This step opens a browser window where you enter your Azure credentials.

    az login

  2. If you have multiple subscriptions, set the active one. Replace <your-subscription-name> with your subscription name or ID.

    az account set --subscription "<your-subscription-name>"

  3. Verify your credentials can access the Learn Platform API.

    az account get-access-token --resource https://learn.microsoft.com

    If successful, you'll see a JSON response with an accessToken field.

  4. Run the examples file using npx to execute the tsx package.

    npx tsx examples.ts

  5. (Optional) Save the output to a file using output redirection.

    npx tsx examples.ts > output.txt 2>&1

Clean up resources

If you no longer need the resources created in this quickstart, you can remove them.

  1. Remove the project folder and all its contents.

    cd ..
rm -rf learn-api-examples

    On Windows PowerShell, use:

    cd ..
Remove-Item -Recurse -Force learn-api-examples

  2. (Optional) Sign out of Azure CLI to remove cached credentials.

    az logout

Note

This quickstart doesn't create any Azure resources that incur costs. The API calls use your existing Azure identity for authentication only.

Related content

  • Last updated on