Azure API Management Samples

This repository provides resources to quickly deploy high-fidelity Azure API Management (APIM) infrastructures and experiment with common APIM.

Historically, there were two general paths to experimenting with APIM. Standing up an entire landing zone with the APIM Landing Zone Accelerator can feel overwhelming and more than needed. Similarly, using APIM policy snippets is only helpful when an APIM instance and infrastructure already exists.

⭐ APIM Samples provides common APIM infrastructures and real-world samples. Most samples can be deployed to any infrastructure, yielding an innovative and highly powerful and flexible à la carte approach!

💡 APIM Samples is _neither too much nor too little. It is just right!

🎯 Objectives

1. Educate on common APIM architectures we see across industries and customers.
2. Empower to safely experiment with APIM policies.
3. Provide high-fidelity building blocks to further your APIM integration efforts.

🚀 Getting Started

It's quick and easy to get started!

1. Follow one of the two setup options.
2. Select an infrastructure to deploy.

📁 List of Infrastructures

Details

Infrastructure Name	Description
Simple API Management	Just the basics with a publicly accessible API Management instance fronting your APIs. This is the innermost way to experience and experiment with the APIM policies.
API Management & Container Apps	APIs are often implemented in containers running in Azure Container Apps. This architecture accesses the container apps publicly. It's beneficial to test both APIM and container app URLs to contrast and compare experiences of API calls through and bypassing APIM. It is not intended to be a security baseline.
Front Door & API Management & Container Apps	A secure implementation of Azure Front Door connecting to APIM via the new private link integration! This traffic, once it traverses through Front Door, rides entirely on Microsoft-owned and operated networks. The connection from APIM to Container Apps is secured but through a VNet configuration (it is also entirely possible to do this via private link). APIM Standard V2 is used here to accept a private link from Front Door.
Application Gateway (Private Endpoint) & API Management & Container Apps	A secure implementation of Azure Application Gateway connecting to APIM via the new private link integration! This traffic, once it traverses through App Gateway, uses a private endpoint set up in the VNet's private endpoint subnet. The connection from APIM to Container Apps is secured but through a VNet configuration (it is also entirely possible to do this via private link). APIM Standard V2 is used here to accept a private link from App Gateway.
Application Gateway (VNet) & API Management & Container Apps	Full VNet injection of APIM and ACA! APIM is shielded from any type of traffic unless it comes through App Gateway. This offers maximum isolation for instances in which customers seek VNet injection.

📁 List of Samples

Details

Sample Name	Description	Supported Infrastructure(s)
AuthX	Authentication and role-based authorization in a mock HR API.	All infrastructures
AuthX Pro	Authentication and role-based authorization in a mock product with multiple APIs and policy fragments.	All infrastructures
General	Basic demo of APIM sample setup and policy usage.	All infrastructures
Load Balancing	Priority and weighted load balancing across backends.	apim-aca, afd-apim (with ACA)
Secure Blob Access	Secure blob access via the valet key pattern.	All infrastructures
Credential Manager (with Spotify)	Authenticate with APIM which then uses its Credential Manager with Spotify's REST API.	All infrastructures
Azure Maps	Proxying calls to Azure Maps with APIM policies.	All infrastructures

🛠️ Developer CLI

Use the interactive Developer CLI to verify setup, run tests, and manage your development workflow:

Windows:

.\start.ps1

macOS / Linux:

./start.sh

This menu-driven interface provides quick access to:

• Setup: Complete environment setup, verify local setup, and show Azure account info
• Tests: Run pylint, pytest, and full Python checks

🏗️ Setup

APIM Samples supports two setup options:

Option 1: GitHub Codespaces / Dev Container (Recommended)

Details

The fastest way to get started is using our pre-configured development environment.

Each supported Python version has its own dev container, providing you with a more tailored environment that hopefully more closely resembles your own workloads.

GitHub Codespaces: Click the green "Code" button → "Codespaces" → "..." → "New with options..." → "Dev container configuration" (select Python version but ignore Default project configuration) → "Create codespace"

VS Code Dev Containers: Alternatively, you can run the dev container locally by installing the Dev Containers extension, then selecting "Reopen in Container".

1. Open the repository in the dev container environment
2. Wait for the automatic setup to complete (includes interactive Azure CLI configuration)
3. If prompted during setup, choose your preferred Azure CLI authentication method:
   • Mount local config: Preserves authentication between container rebuilds
   • Manual login: Requires tenant-specific az login after each container startup
   • Configure later: Skip for now, configure manually later
4. Sign in to Azure with correct tenant and subscription:
   • If you chose manual login or skipped: az login --tenant <your-tenant-id-or-domain>
   • Set the correct subscription: az account set --subscription <your-subscription-id-or-name>
   • Verify your authentication context: az account show
5. Verify your Azure setup by executing shared/jupyter/verify-az-account.ipynb

All prerequisites are automatically installed and configured.

📖 For detailed setup information, troubleshooting, and optimization details, see Dev Container Documentation

Option 2: Full Local Setup

Details

📋 Prerequisites

These prerequisites apply broadly across all infrastructure and samples. If there are specific deviations, expect them to be noted there.

• Python 3.12, 3.13, and 3.14 are all supported
• VS Code installed with the Jupyter notebook extension enabled
• Azure CLI installed
• Azure Bicep installed
• An Azure Subscription with Owner or Contributor+UserAccessAdministrator permissions. Execute Verify Azure Account to verify.
• Azure Authentication: Sign in to Azure with Azure CLI using the specific tenant and subscription you want to work with:
  • To log in to a specific tenant: az login --tenant <your-tenant-id-or-domain>
  • To set a specific subscription: az account set --subscription <your-subscription-id-or-name>
  • To verify your current context: az account show
  • See the Azure CLI authentication guide for more options

Manual Local Setup

1. Create Python Environment: In VS Code, use Ctrl+Shift+P → "Python: Create Environment" → "Venv" → Select Python version → Check requirements.txt
   The install may take a few minutes. You can check on progress in the OUTPUT window (select Python).
2. Complete Environment Setup: Open a terminal and start the Developer CLI, then select Complete environment setup.
3. Restart VS Code to apply all settings
4. Sign in to Azure: az login --tenant <your-tenant-id> and az account set --subscription <your-subscription>
5. Verify local setup: Start the Developer CLI, then select Verify local setup.

The first time you run a Jupyter notebook, you may be asked to install the Jupyter kernel package (ipykernel) if not already available. When you open any .ipynb notebook, it will automatically use the correct kernel and all imports will work seamlessly.

🚀 Sample Deployments

1. Open the desired sample's create.ipynb file.
2. Optional: Adjust the parameters under the User-defined Parameters header, if desired.
3. Execute the create.ipynb Jupyter notebook via Run All.

A supported infrastructure does not yet need to exist before the sample is executed. The notebook will determine the current state and present you with options to create or select a supported infrastructure, if necessary.

Now that infrastructure and sample have been stood up, you can experiment with the policies, make requests against APIM, etc.

🔎 Logging and Output

The Python helpers in this repo use standard-library logging, empowering you to control verbosity via environment variables in the root .env file. This file is created via the APIM Samples Developer CLI.

• APIM_SAMPLES_LOG_LEVEL: Controls the overall verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default: INFO.
  • When set to DEBUG, the Azure CLI runner in shared/python/azure_resources.py will also add --debug to simple az ... commands.
• APIM_SAMPLES_CONSOLE_WIDTH: Optional wrap width for long lines (defaults to 120).

Troubleshooting

Encountering issues? Check our comprehensive Troubleshooting Guide! which covers:

• Deployment Errors - Including the common "content already consumed" error and parameter mismatches
• Authentication Issues - Azure CLI login problems and permission errors
• Notebook & Development Environment Issues - Module import errors and Python path problems
• Azure CLI Issues - Rate limiting and API version compatibility
• Resource Management Issues - Resource group and APIM service problems

For immediate help with common errors, diagnostic commands, and step-by-step solutions, see TROUBLESHOOTING.md.

📂 Repo Structure

🦅 High-level

• All samples can be found in the samples folder. Samples showcase functionality and provide a baseline for your experimentation.
• All infrastructures can be found in the infrastructure folder. They provide the architectural underpinnings.
• All shared code, modules, functionality, policies, etc. can be found in the shared folder.
  • Bicep modules are versioned in the bicep/modules folder. Major changes require versioning.
  • Python modules are found in the python folder. They are not versioned yet but may be in the future.
  • Reusable APIM policies are found in the apim-policies folder.
  • Reusable Jupyter notebooks are found in the jupyter folder.

⚙️ Sample Setup

• Each sample uses an architecture infrastructure. This keeps the samples free of almost all setup.
• Each infrastructure and sample features a create.ipynb for creation (and running) of the sample setup and a main.bicep file for IaC configuration.
• Each infrastructure contains a clean-up.ipynb file to tear down everything in the infrastructure and its resource group. This reduces your Azure cost.
• Samples (and infrastructures) may contain additional files specific to their use cases.

🏛️ Infrastructure Architectures

We provide several common architectural approaches to integrating APIM into your Azure ecosystem. While these are high-fidelity setups, they are not production-ready. Please refer to the Azure API Management landing zone accelerator for up-to-date production setups.

🛠️ Development

As you work with this repo, you will likely want to make your own customizations. There's little you need to know to be successful.

The repo uses the bicep linter and has rules defined in bicepconfig.json. See the bicep linter documentation for details.

We welcome contributions! Please consider forking the repo and creating issues and pull requests to share your samples. Please see CONTRIBUTING.md for details. Thank you!

🔍 Code Quality & Linting

The repository uses pylint to maintain Python code quality standards. The configuration is located in tests/python/.pylintrc, and the Developer CLI supports linting.

🧪 Testing & Code Coverage

Python modules in shared/python are covered by comprehensive unit tests located in tests/python. All tests use pytest and leverage modern pytest features, including custom markers for unit and HTTP tests. The Developer CLI supports testing.

➕ Adding a Sample

Adding a new sample is relatively straight-forward.

1. Create a new feature branch for the new sample.
2. Copy the /samples/_TEMPLATE folder.
3. Rename the copied folder to a name representative of the sample (e.g. "load-balancing", "authX", etc.)
4. Change the create.ipynb and main.bicep files. Look for the brackets ([ ]) brackets for specific inputs.
5. Add any policy.xml files to the same folder if they are specific to this sample. If they are to be reused, place them into the /shared/apim-policies folder instead.
6. Test the sample with all supported infrastructures.
7. Create a pull request for merge.

🙏 Acknowledgements

This project has its roots in work done by Alex Vieira on the excellent Azure API Management AI Gateway GitHub repository. Much of the structure is similar and its reuse resulted in significant time savings. Thank you, Alex!

Furthermore, Houssem Dellai was instrumental in setting up a working Front Door to API Management private connectivity lab. This created a working baseline for one of this repository's infrastructures. Thank you, Houssem!

Andrew Redman for contributing the Azure Maps sample.

The original author of this project is Simon Kurtz.

🥇 Other resources

• AI Gateway
• Landing Zone Accelerator
• Learning Modules
• News and announcements
• APIM Releases
• APIM policy snippets repo

For much more API Management content, please also check out APIM Love.

📜 Disclaimer

Important

This software is provided for demonstration purposes only. It is not intended to be relied upon for any purpose. The creators of this software make no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability or availability with respect to the software or the information, products, services, or related graphics contained in the software for any purpose. Any reliance you place on such information is therefore strictly at your own risk.