APIM backends as code

Problem

On Azure API Management, the public path exposed to clients (OpenAPI paths) is different from the HTTP backend APIM forwards to (set-backend-service).

OpenAPI import (az apim api import) cannot set a backend per operation. Without a dedicated step, backends are edited manually in the portal — which causes drift across INTE / TEST_FW / ENV5 / COMPTA.

Model

backendUrl = https://{environment.backendHost}{x-backend-path}

Concept	Where	ENV5 example
Public path (client)	OpenAPI `paths`	`/getAnalyticalBalance`
Backend path	`x-backend-path` extension	`/collaborateur/service/publicapi/service/generate-balance`
Backend host	`backends/config.json`	`testenv005.loopsoftware.fr`
APIM backend URL	computed	`https://testenv005.loopsoftware.fr/collaborateur/service/publicapi/service/generate-balance`

The backend path is identical across all environments. Only the host changes.

Files

File	Purpose
`backends/config.json`	Hosts / apiId / gateway URL per environment
`backends/operations.json`	Mapping `method` + `public-path` → `backend-path`
`src/generateAPIM.js`	Injects `x-backend-path` into the generated OpenAPI
`src/applyBackends.js`	After APIM import, applies `set-backend-service`

Pipeline

npm run generate-apim -- --target=<ENV> → OpenAPI with x-backend-path
az apim api import → create/update public paths
npm run apply-backends -- --target=<ENV> ... → set operation backends

Add / update a backend

Edit backends/operations.json:

{
  "method": "POST",
  "public-path": "/exportFec",
  "backend-path": "/collaborateur/service/publicapi/service/fec",
  "displayName": "Export FEC"
}

public-path must match the OpenAPI path key in APIM/Loop/** (without query string).

(Optional) also add the operation under APIM/Loop/** so it appears in the public swagger.
Re-run the pipeline for the target environment.

Local run

cd APIM
npm ci
npm run generate-apim -- --path=./Loop --output=./generatedApimOutput --filename=out.json --target=ENV5

az account set --subscription 8396-INTE-APIM
npm run apply-backends -- \
  --spec=./generatedApimOutput/out.json \
  --target=ENV5 \
  --subscription=8396-INTE-APIM \
  --resource-group=rsg839600pasi01-application \
  --service-name=LBA839600AMAI01 \
  --report=./generatedApimOutput/backends-report.json

Notes

operations.json public-path must match OpenAPI path keys (e.g. /compteBancaire), not APIM urlTemplates with query strings.
x-backend-path is an OpenAPI vendor extension: ignored by clients, consumed only by applyBackends.js.
Operations without a mapping keep the API-level serviceUrl (fallback).
Do not confuse servers[].url (documented gateway URL) with backendHost (real Loop host).

Table of Contents