Aspirerelease/17.0

Azure API Management APIs and operations

このコンテンツはまだ日本語訳がありません。

An API in Azure API Management (APIM) is a set of operations published at a path on the gateway. The Aspire Azure API Management hosting integration models each API as an AzureApiManagementApiResource child of the service. This page assumes the apim resource and the catalog workload from Get started with Azure API Management.

Call AddApi with a compute resource to publish that workload through the gateway. The compute resource must expose an HTTP or HTTPS endpoint and have an Azure compute environment, such as an Azure Container Apps environment.

apphost.mts
await apim.addApi("catalog-api", catalog, "catalog", {
displayName: "Catalog API",
subscriptionRequired: true,
apiName: "catalog-v1",
});

For each compute-targeted API, Aspire deploys:

  • An API that accepts HTTPS requests at the path that you specify.
  • A reusable APIM backend whose URL is the workload’s deployed endpoint, with TLS certificate-chain and hostname validation enabled.
  • Catch-all operations that forward requests to that backend. For more information, see Generated proxy operations.
  • An API policy that inherits the parent policy and sets the backend service.

The AddApi method has the following parameters:

ParameterRequiredDescription
nameYesThe Aspire resource name. It’s also the default physical API name.
targetCompute-targeted onlyThe compute resource to route to.
pathYesThe public path beneath the gateway host name. Surrounding slashes are trimmed.
displayNameNoThe API display name. Defaults to the resource name.
subscriptionRequiredNoWhether callers must send an APIM subscription key. Defaults to true.
apiNameNoThe physical API identifier in APIM. Defaults to the resource name.

Aspire validates these values when you add the API:

  • The physical API name is at most 256 characters and can’t contain *, #, &, +, :, <, >, or ?.
  • The path is non-empty after trimming and has at most 400 characters.
  • The display name has 1 to 300 characters.
  • The physical API name and the path are each unique within the service, ignoring case.

APIM selects the first external HTTP or HTTPS endpoint of the workload, or the first HTTP or HTTPS endpoint when none is external. If the workload exposes no HTTP or HTTPS endpoint, publishing fails with the error Resource 'catalog' does not have an HTTP or HTTPS endpoint.

A workload that exposes only internal endpoints is reachable only when the APIM service has virtual network connectivity. For more information, see Virtual networking.

Use the overload without a compute target when the API should forward to a backend that isn’t an Aspire compute resource, such as an external service. Then attach a backend or a backend pool with WithBackend.

apphost.mts
import { refExpr } from './.aspire/modules/aspire.mjs';
const backend = await apim.addBackend("legacy-backend", refExpr`https://legacy.example.com`);
const legacyApi = await apim.addApiWithoutTarget("legacy-api", "legacy");
await legacyApi.withApiBackend(backend);

In TypeScript, the overload without a target is addApiWithoutTarget. An API without a compute target must have exactly one backend or pool when you deploy. Aspire throws an InvalidOperationException if the API has none, if it already has one, if it targets a compute resource, or if the backend belongs to a different APIM service.

For backend options, backend pools, and managed identity authentication, see Backends and backend pools.

APIM needs operations to dispatch requests. When an API has no OpenAPI import, Aspire generates a root operation and a catch-all operation for each of the eight supported HTTP methods:

Operation nameURL templateMatches
proxy-{method}-root/The API path itself, such as /catalog.
proxy-{method}/{*path}Any descendant path, such as /catalog/products/1.

The methods are DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, and TRACE. APIM doesn’t reliably dispatch operations that use the wildcard method, so Aspire creates a concrete operation for each method. The wildcard route doesn’t match the API path itself, which is why Aspire also generates the root operations.

When you import an OpenAPI document, the imported operations replace the generated proxy operations. For more information, see OpenAPI import.

Call AddOperation to model an operation explicitly, for example to attach a policy to a specific route. Explicit operations are provisioned in addition to the generated proxy operations or the imported operations.

apphost.mts
const catalogApi = await apim.addApi("catalog-api", catalog, "catalog");
await catalogApi.addOperation("get-product", "GET", "/products/{id}", {
displayName: "Get product",
});
await catalogApi.addOperation("create-product", "POST", "/products");

Each placeholder in the URL template, such as {id}, becomes a required string template parameter. The AddOperation method has the following parameters:

ParameterRequiredDescription
nameYesThe Aspire resource name. It’s also the default physical operation name.
methodYesA concrete HTTP method. Aspire converts it to uppercase. The wildcard * isn’t allowed.
urlTemplateYesThe URL template relative to the API path. Maximum 1,000 characters.
displayNameNoThe operation display name. Defaults to the resource name.
operationNameNoThe physical operation identifier in APIM. Defaults to the resource name. Maximum 80 characters.

Aspire enforces these rules:

  • The physical operation name is unique within the API.
  • The HTTP method and URL template are unique within the API. Templates that differ only in parameter names, such as /products/{id} and /products/{productId}, count as the same route.
  • The names proxy, proxy-{method}, and proxy-{method}-root are reserved for generated operations.
  • The routes / and /{*path} are reserved for generated proxy operations. You can use them only when the API has an OpenAPI import, regardless of whether you call WithOpenApiDocument before or after AddOperation.

Operations support operation-level policies. For more information, see Policies and named values.

Call AddOpenAIApi to publish an API that forwards OpenAI-style requests to a backend pool. The method creates an API with the generated proxy operations and an explicit POST /chat/completions operation named chat-completions.

apphost.mts
const foundry = await builder.addFoundry("foundry");
const chat = await foundry.addDeployment("chat", {
name: "gpt-5-mini",
version: "2025-08-07",
format: "OpenAI",
});
const backend = await apim.addFoundryBackend("foundry-backend", chat);
const openAIApi = await apim.addOpenAIApi("openai-api", "openai", {
subscriptionRequired: false,
});
await openAIApi.withApiBackend(backend);

Requests beneath the API path are appended to the URI of the selected backend. You can attach a single backend, as in the preceding example, or a backend pool that load balances several deployments. Create the backends with AddAzureOpenAIBackend or AddFoundryBackend. For a pool example, see Load balance OpenAI deployments.