sample-creator

Sample Creator

This skill guides creating new APIM samples that follow the repository's established patterns.

Before adding or changing any dependency, require a release at least seven days old. Preserve the uv release exclusion and locked install flow, and run python setup/verify_dependency_age.py --scope all before final validation.

Sample Structure

Every sample under samples/ must contain these files:

samples/<sample-name>/
├── README.md              (documentation)
├── create.ipynb           (Jupyter notebook for deployment)
├── main.bicep             (infrastructure as code)
├── <domain>_helpers.py    (optional: sample-local Python mechanics)
├── apim-policies/         (optional: sample-owned APIM policy XML)
│   └── *.xml
└── queries/               (optional: sample-owned KQL queries)
    └── *.kql

Step 1: Gather Requirements

Before creating the sample, collect:

1. Sample name - kebab-case folder name (e.g., oauth-validation, rate-limiting). If the user has not provided it, ask before creating files.

2. Display name - Human-readable title for README

3. Description - Brief explanation of what the sample demonstrates

4. Supported infrastructures - Which infrastructure architectures work with this sample:

   • INFRASTRUCTURE.AFD_APIM_PE - Azure Front Door + APIM with Private Endpoint
   • INFRASTRUCTURE.APIM_ACA - APIM with Azure Container Apps
   • INFRASTRUCTURE.APPGW_APIM - Application Gateway + APIM
   • INFRASTRUCTURE.APPGW_APIM_PE - Application Gateway + APIM with Private Endpoint
   • INFRASTRUCTURE.SIMPLE_APIM - Basic APIM setup

   If the user has not provided supported infrastructures, ask before scaffolding the sample.

5. Learning objectives - What users will learn (3-5 bullet points)

6. APIs to create - List of APIs with operations, paths, and policies

7. Policy requirements - Any custom APIM policies needed

8. Downstream updates - Whether the sample requires updates to the website, slide deck, or compatibility artifacts. Default to yes for new samples.

9. Helper boundary - Which parts are educational scenario content and which are incidental mechanics such as parsing, retries, sessions, persistence, command composition, polling, or cleanup.

Step 2: Create the Sample Folder

Create the folder structure under samples/ unless the user explicitly requests another location:

mkdir samples/<sample-name>

Start from samples/_TEMPLATE/ and compare the result against at least one similar existing sample before finalizing.

Step 3: Create README.md

Use this template:

# Samples: <Display Name>

<Brief description of what this sample demonstrates>

⚙️ **Supported infrastructures**: <Comma-separated list or "All infrastructures">

👟 **Expected *Run All* runtime (excl. infrastructure prerequisite): ~<N> minute(s)**

## 🎯 Objectives

1. <Learning objective 1>
1. <Learning objective 2>
1. <Learning objective 3>

<!-- ## ✅ Prerequisites -->

<!-- ONLY ADD THIS SECTION IF THE SAMPLE HAS REQUIREMENTS BEYOND THE ROOT README'S GENERAL PREREQUISITES (Azure subscription, CLI, Python, APIM instance). Examples: additional RBAC roles, external service accounts, special tooling. Open with a one-line reference to the root README, then list only sample-specific requirements. DELETE THIS COMMENT BLOCK IF NOT NEEDED. -->

## 📝 Scenario

<Optional: Describe the use case or scenario if applicable. Delete section if not needed.>

## 🛩️ Lab Components

<Describe what the lab sets up and how it benefits the learner.>

## ⚙️ Configuration

1. Decide which of the [Infrastructure Architectures](../../README.md#infrastructure-architectures) you wish to use.
    1. If the infrastructure _does not_ yet exist, navigate to the desired [infrastructure](../../infrastructure/) folder and follow its README.md.
    1. If the infrastructure _does_ exist, adjust the `user-defined parameters` in the _Initialize notebook variables_ below.

Step 4: Create create.ipynb

Before writing cells, apply the helper-placement sequence from shared/python/README.md:

1. Keep user configuration, scenario declarations, APIM concepts, expected outcomes, and assertions visible in the notebook.
2. Compose established NotebookHelper, ApimRequests, ApimTesting, and azure_resources boundaries directly.
3. Put one-sample mechanics in a descriptive samples/<sample-name>/<domain>_helpers.py module.
4. Promote behavior to shared/python/ only when at least two active consumers need the same stable contract.
5. Give helpers explicit inputs and typed outputs, deterministic resource cleanup, and injectable remote or timing boundaries for unit tests.

Line count alone does not determine extraction. Extract behavior because its responsibility, lifecycle, repetition, or testability belongs outside the educational workflow.

The notebook must contain these cells in order:

Cell 1: Markdown - Initialize Header

### 🛠️ Initialize Notebook Variables

**Only modify entries under _USER CONFIGURATION_.**

Cell 2: Python - Initialization

import importlib
import sys
from pathlib import Path
from typing import List

import utils

from apimtypes import API, APIM_SKU, GET_APIOperation, INFRASTRUCTURE, POST_APIOperation, Region
from console import print_error, print_ok
from azure_resources import get_account_info, get_infra_rg_name

# ------------------------------
#    USER CONFIGURATION
# ------------------------------

rg_location = Region.EAST_US_2
index       = 1
apim_sku    = APIM_SKU.BASICV2              # Options: 'DEVELOPER', 'BASIC', 'STANDARD', 'PREMIUM', 'BASICV2', 'STANDARDV2', 'PREMIUMV2'
deployment  = INFRASTRUCTURE.<DEFAULT>      # Options: see supported_infras below
api_prefix  = '<prefix>-'                   # ENTER A PREFIX FOR THE APIS TO REDUCE COLLISION POTENTIAL
tags        = ['<tag1>', '<tag2>']          # ENTER DESCRIPTIVE TAGS



# ------------------------------
#    SYSTEM CONFIGURATION
# ------------------------------

sample_folder    = '<sample-name>'
rg_name          = get_infra_rg_name(deployment, index)
supported_infras = [<LIST_OF_SUPPORTED_INFRASTRUCTURES>]
nb_helper        = utils.NotebookHelper(sample_folder, rg_name, rg_location, deployment, supported_infras, index = index, apim_sku = apim_sku)

# Add only when this sample has a sample-local helper module.
# sample_dir = str(Path(utils.determine_policy_path('<domain>_helpers.py', sample_folder)).parent)
# if sample_dir not in sys.path:
#     sys.path.insert(0, sample_dir)
# sample_helpers = importlib.import_module('<domain>_helpers')
# utils.enable_module_autoreload('<domain>_helpers')

# Get account info (returns: current_user, current_user_id, tenant_id, subscription_id)
_, _, _, subscription_id = get_account_info()

# Define the APIs and their operations and policies
# <Add policy loading if needed>
# pol_example = utils.read_policy_xml('<policy-file>.xml', sample_name = sample_folder)

# API Operations
# get_op = GET_APIOperation('Description of GET operation')
# post_op = POST_APIOperation('Description of POST operation')

# APIs
# api1_path = f'{api_prefix}<name>'
# api1 = API(api1_path, '<API Display Name>', api1_path, '<API Description>', operations = [get_op], tags = tags)
# api2 = API(api2_path, '<API Display Name>', api2_path, '<API Description>', '<policy_xml>', [get_op, post_op], tags)

# APIs Array
apis: List[API] = []  # Add your APIs here

print_ok('Notebook initialized')

Cell 3: Markdown - Deploy Header

### 🚀 Deploy Infrastructure and APIs

Creates the bicep deployment into the previously-specified resource group. A bicep parameters, `params.json`, file will be created prior to execution.

Cell 4: Python - Deployment

# Build the bicep parameters
if 'nb_helper' not in locals():
    raise SystemExit(1)

bicep_parameters = {
    'apis': {'value': [api.to_dict() for api in apis]}
}

# Deploy the sample
output = nb_helper.deploy_sample(bicep_parameters)
deployment_context = nb_helper.get_deployment_context(output)
apim_name = deployment_context.apim_name
apim_gateway_url = deployment_context.apim_gateway_url
apim_apis = deployment_context.apis

print_ok('Deployment completed successfully')

Cell 5: Markdown - Verify Header

### ✅ Verify API Request Success

Assert that the deployment was successful by making calls to the deployed APIs.

Cell 6: Python - Verification

Use ApimRequests and ApimTesting for structured test verification with verbose logging. If the sample also needs traffic generation loops (multi-caller simulation, load generation, etc.), add separate cells that use requests.Session() instead — see the "Testing and Traffic Generation" section in copilot-instructions.md for the session pattern.

from apimtesting import ApimTesting

if 'deployment_context' not in locals():
    raise SystemExit(1)

# Initialize testing framework
tests = ApimTesting('<Sample Name> Tests', sample_folder, nb_helper.deployment)

# ********** TEST EXECUTIONS **********

# Example: Test API response
# subscription_key = apim_apis[0]['subscriptionPrimaryKey']
# with nb_helper.create_apim_requests(apim_gateway_url, subscription_key) as reqs:
#     response = reqs.singleGet('/<api-route>', msg = 'Testing API. Expect 200.')
# tests.verify('Expected String' in response, True)

tests.print_summary()

print_ok('All done!')

Optional Sample-Local Helper

Create samples/<sample-name>/<domain>_helpers.py when notebook cells would otherwise own incidental mechanics. Prefer a function for one stateless operation, an immutable dataclass for a multi-value result, and a class only when operations share validated state or an owned lifecycle.

The helper must:

• Use explicit inputs and return values; never inspect notebook globals or IPython state.
• Import Azure operations through import azure_resources as az and compose existing shared

---

Content truncated.