| name | add-apim-api |
| description | Scaffold a new API in Azure API Management. Use when user asks to add, create, or expose a new API through APIM, or needs to wire up a backend service to the gateway. |
| compatibility | Azure CLI with the Bicep extension, and an existing APIM Bicep infrastructure project. No live Azure deployment is performed. |
| version | 1.1.0 |
Add APIM API
Scaffold a new API in Azure API Management with Bicep infrastructure.
Determinism checklist
Before declaring this skill run complete:
- Scope fixed: inputs and target files are explicit.
- Read-first: inspect current state before edits.
- Plan-first: preview actions before writes when tooling supports it.
- Confirm-before-write: get user confirmation before destructive or broad writes.
- One step, one done-test: each step has a checkable completion criterion.
- Verify outcomes: run the smallest available validation commands.
- Report skips: list what was skipped and why.
- Stop on blockers: capture exact failing command and error summary.
Steps
1. Gather requirements
Collect from user or infer from context:
- API name — display name and kebab-case identifier (e.g.,
speeches-api)
- Backend URL — the upstream service endpoint
- Path prefix — gateway path (e.g.,
/speeches)
- Access — open (no subscription) or protected (subscription key required)
- Operations — method, URL template, parameters per operation
If protected, determine whether backend needs an API key from Key Vault.
Done when: all five fields known.
2. Scaffold files
Create in order:
infra/modules/api-management/apis/{api-name}.bicep — API definition with CORS, rate limiting, caching policiesinfra/modules/api-management/operations/{api-name}-operations.bicep — operation definitions following naming conventions below
Follow patterns in references/bicep-patterns.md for Bicep structure.
If backend API key needed:
infra/modules/api-management/named-values/{api-name}-key.bicep — Key Vault referenceinfra/modules/api-management/policies/{api-name}-policy.bicep — policy injecting the key
Done when: all files created and compile with az bicep build.
3. Wire up
Update existing modules:
infra/modules/api-management/api-management.bicep — add module referencesinfra/modules/api-management/products/{product-name}.bicep — associate API with product (if applicable)infra/main.bicepparam — add Front Door route (if new path prefix)
Done when: az bicep build --file infra/main.bicep succeeds.
Operation naming conventions
| Verb | Use | Example |
|---|
list | collection | listMinistries, listConsultations |
get | single item | getResponse, getCatalog |
create | new item | createSubscription |
update | modify | updateDocument |
delete | remove | deleteComment |
Rules:
- English identifiers, lowerCamelCase
list + plural (listMinistries), get + singular (getResponse)- Never
fetch or retrieve — use list or get
