Add Apim-Samples files

Author: simonkurtz-MSFT

.editorconfig

@@ -0,0 +1,23 @@
+# https://editorconfig.org/
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+end_of_line = lf
+charset = utf-8
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.bicep]
+indent_size = 2
+
+[*.yaml]
+indent_size = 2
+
+[*.yml]
+indent_size = 2

.github/workflows/python-tests.yml

@@ -0,0 +1,27 @@
+name: Python Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.12', '3.13' ]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+      - name: Run tests
+        run: |
+          python -m unittest discover shared/python-tests

.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+env/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# VS Code
+.vscode/
+
+# Azure
+.azure/
+
+# Bicep/ARM/Infra
+params*.json
+policy-updated.xml
+labs-in-progress/
+
+# Misc
+*.log
+
+# Exclude sensitive or generated files
+.env

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to Azure API Management Samples
+
+Thank you for your interest in contributing!
+
+## How to Contribute
+
+- Fork the repository and create your branch from `main`.
+- Make your changes, following the existing code style and structure.
+- Add or update documentation and tests as needed.
+- Ensure your code passes linting and runs as expected.
+- Open a pull request with a clear description of your changes.
+
+## Guidelines
+
+- Use standard Python and Bicep best practices.
+- Keep reusable assets in the `shared` folder.
+- For infrastructure or sample changes, update the relevant `create.ipynb` and `main.bicep` files.
+- Keep documentation clear and concise.
+
+## Code of Conduct
+
+Please be respectful and considerate in all interactions.
+
+---
+
+For questions or suggestions, please open an issue or reach out to the author.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Simon Kurtz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,108 @@
-# Apim-Samples
-This repository provides a playground to safely experiment with and learn Azure API Management (APIM) policies in various architectures.
+# Azure API Management Samples
+
+This repository provides a playground to safely experiment with and learn Azure API Management (APIM) policies in various architectures. 
+
+## Objectives
+
+1. Educate you on common APIM architectures we see across industries and customers.
+1. Empower you to safely experiment with APIM policies.
+1. Provide you with high-fidelity building blocks to further your APIM integration efforts.
+
+_Try it out, learn from it, apply it in your setups._
+
+## 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](https://learn.microsoft.com/azure/cloud-adoption-framework/scenarios/app-platform/api-management/landing-zone-accelerator) for up-to-date production setups.
+
+- [Simple API Management](./infrastructure/simple-apim)
+  - Just the basics with a publicly accessible API Management intance fronting your APIs. This is the innermost way to experience and experiment with the APIM policies. 
+- [API Management & Container Apps](./infrastructure/apim-aca)
+  - APIs are often times implemented in containers that are running in Azure Container Apps. This architecture accesses the container apps publicly. It's beneficial to test both APIM and container app URLs here to contrast and compare experiences of API calls through and bypassing APIM. It is not intended to be a security baseline.
+- [Secure Front Door & API Management & Container Apps](./infrastructure/afd-apim)
+  - A higher-fidelity implementation of a secured setup in which Azure Front Door connects to APIM via the new private link integration. This traffic, once it traverses through Front Door, rides entirely on Microsoft-owned and operated networks. Similarly, 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). It's noteworthy that we are using APIM Standard V2 here as we need the ability to accept a private link from Front Door.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+These prerequisites apply broadly across all infrastructure and samples. If there are specific deviations, expect them to be noted there.
+
+- [Python 3.12](https://www.python.org/) installed
+  - Python 3.13 may not have all dependencies ready yet. There have been issues during installs.
+- [VS Code](https://code.visualstudio.com/) installed with the [Jupyter notebook extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) enabled
+- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed
+- [An Azure Subscription](https://azure.microsoft.com/free/) with Owner or Contributor+UserAccessAdministrator permissions. Execute [shared/jupyter/verify-az-account.ipynb](shared/jupyter/verify-az-account.ipynb) to verify.
+- [Sign in to Azure with Azure CLI](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively)
+
+### Initialization
+
+Run through the following steps to create a Python virtual environment before doing anything else:
+
+1. Open VS Code.
+1. Invoke the _Command Palette_ via the _View_ menu or a shortcut (on Windows: Ctrl + Shift + P).
+1. Select _Python: Create Environment_.
+1. Select _Venv_ as we want a local virtual environment.
+1. Select the desired, installed Python version.
+1. Check _requirements.txt_ to install the Python dependencies we need for this repo, then press _OK_. The install may take a few minutes. You can check on progress in the _OUTPUT_ window.
+1. Verify the virtual environment is set up. You should see a new _.venv_ directory with a _pyveng.cfg_ file and the Python version you selected earlier.
+
+The first time you run a Jupyter notebook, you'll be asked to install the Jupyter kernel package (ipykernel).
+
+### Running a Sample
+
+1. Locate the specific sample's `create.ipynb` file and adjust the parameters under the `User-defined Parameters` header as you see fit.
+1. Ensure that the specified infrastructure already exists in your subscription. If not, proceed to the desired infrastructure folder and execute its `create.ipynb` file. Wait until this completes before continuing.
+1. Execute the sample's `create.ipynb` file.
+
+Now that infrastructure and sample have been stood up, you can experiment with the policies, make requests against APIM, etc.
+
+---
+
+## 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](https://learn.microsoft.com/azure/azure-resource-manager/bicep/bicep-config-linter) for details.
+
+We welcome contributions! Please consider forking the repo and creating issues and pull requests to share your samples. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. Thank you! 
+
+### Testing
+
+Python modules and files in the `shared` folder are supported with tests in the `python-tests` folder. They can be invoked manually via `pytest -v` but are also run upon push to GitHub origin. The `pytest.ini` file in the root sets up the test structure.
+
+Additional information can be found [here](# https://docs.pytest.org/en/8.2.x/).
+
+---
+
+## Supporting Resources
+
+The APIM team maintains an [APIM policy snippets repo](https://github.com/Azure/api-management-policy-snippets) with use cases we have seen. They are not immediately executable samples and require integrations such as in this repo.
+
+---
+
+## Acknowledgements
+
+This project has its roots in work done by [Alex Vieira](https://github.com/vieiraae) on the excellent Azure API Management [AI Gateway](https://github.com/Azure-Samples/AI-Gateway) GitHub repository. Much of the structure is similar and its reuse resulted in significant time savings. Thank you, Alex!
+
+Furthermore, [Houssem Dellai](https://github.com/HoussemDellai) was instrumental in setting up a working Front Door to API Management [private connectivity lab](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/private-connectivity). This created a working baseline for one of this repository's infrastructures. Thank you, Houssem! 

bicepconfig.json

@@ -0,0 +1,18 @@
+{
+    "analyzers": {
+      "core": {
+        "enabled": true,
+        "rules": {
+          "no-unused-params": {
+            "level": "off"
+          },
+          "no-unused-vars": {
+            "level": "off"
+          },
+          "outputs-should-not-contain-secrets": {
+            "level": "off"
+          }
+        }
+      }
+    }
+  }

diagrams/README.md

@@ -0,0 +1,48 @@
+# PlantUML Diagrams
+
+This directory contains PlantUML diagrams for the Azure API Management architecture.
+Azure Symbols are on [GitHub](https://github.com/plantuml-stdlib/Azure-PlantUML/blob/master/AzureSymbols.md)
+
+## Using PlantUML in VS Code
+
+1. **Prerequisites**:
+   - Java is installed (e.g. OpenJDK 22)
+   - PlantUML VS Code extension is installed
+   - Graphviz (optional, for more complex diagrams)
+   - Configure PlantUML settings in `.vscode\settings.json`. Ensure that you set the `plantuml.java` path appropriately for your Java executable:
+
+   ```json
+   "plantuml.render": "Local",
+   "plantuml.exportFormat": "svg",
+   "plantuml.java": "C:\\Program Files\\OpenJDK\\jdk-22.0.2\\bin\\java.exe",
+   "plantuml.diagramsRoot": "diagrams/src",
+   "plantuml.exportOutDir": "diagrams/out"
+   ```
+
+2. **Viewing Diagrams**:
+   - Open any `.puml` file in this directory
+   - Right-click in the editor and select "PlantUML: Preview Current Diagram"
+   - Alternatively, use the Alt+D keyboard shortcut
+
+3. **Exporting Diagrams**:
+   - Right-click in the editor and select "PlantUML: Export Current Diagram"
+   - Select your desired output format (PNG, SVG, PDF, etc.)
+
+## Troubleshooting
+
+If you encounter issues with PlantUML:
+
+1. **Java Path Issues**:
+   - Ensure Java is on your system PATH
+   - If VS Code terminal can't find Java, try restarting VS Code
+   - You may need to configure the specific Java path in VS Code settings
+
+2. **PlantUML Extension Configuration**:
+   - Open VS Code settings (Ctrl+,)
+   - Search for "plantuml"
+   - Set "plantuml.java" to the path of your Java executable if needed
+   - You can also set "plantuml.jarPath" to a specific PlantUML jar file
+
+3. **Alternative Rendering**:
+   - If local rendering fails, try using the PlantUML server:
+   - Change "plantuml.render" setting to "PlantUMLServer"