The endpoint path enables APIM 3.0 to route and resolve requests. In endpoint configuration, the Routing method section includes a Path field.

Select Rules or Expression, then enter the Path. Rules is the default and is all you need for basic routing.

When two endpoints share the same path, use rules or expressions to determine which endpoint handles a given request — for example, routing US-locale traffic to one endpoint and EMEA-locale traffic to another. Use:

• Rules when the match condition is one or more name-value pairs, such as a required header or query parameter value.
• Expressions when the match condition needs arbitrary boolean logic across the request.

Both rules and expressions have a Path field and an optional Upstream Path field:

• Path: Required. A pattern that incoming requests must match. Path parameters are named variable segments of the URL — enclose them in curly braces to capture their values. For example, in /orders/{orderId}, {orderId} captures 42 from a request to /orders/42.
• Upstream Path: Optional. Shapes the path that APIM 3.0 forwards after matching the request. It is a template that APIM 3.0 fills in with path-parameter values from the incoming request. For native endpoints, it controls the PATH_INFO value the pipeline receives. For external endpoints, it shapes the path appended to the Upstream URL. For example, you can expose /orders/{orderId} to clients while forwarding a different path to the upstream destination.

At runtime, these field values have different uses for the two types of endpoints:

• For a native endpoint (a Triggered Task or Ultra Task pipeline):
  • If Upstream Path is empty, APIM 3.0 resolves the endpoint Path (substituting path-parameter values) and sends it as PATH_INFO. This behavior requires release 4.45 or later.
  • If Upstream Path is populated, APIM 3.0 resolves the Upstream Path (substituting path-parameter values) and sends it as PATH_INFO instead.

  Refer to Pass pipeline arguments to Triggered Task for details on reading PATH_INFO in a pipeline.

• For an external endpoint (one proxied to a third-party server): APIM 3.0 concatenates the endpoint's Upstream URL with the Upstream Path (after substituting path parameters) and sends the outbound URL to the third-party server. For example, with Upstream URL https://api.github.com/repos/acme/widgets and Upstream Path /issues/{issueId}, APIM 3.0 forwards a request to /issues/42 as https://api.github.com/repos/acme/widgets/issues/42.

If the incoming request includes path segments beyond the matched route, APIM 3.0 appends those trailing segments to the resolved path. For example, a request to /orders/42/items/9 matched against route /orders/{orderId} captures orderId=42 and treats /items/9 as trailing segments, which APIM 3.0 appends after substitution.

Empty Upstream Path

When Upstream Path is empty, behavior depends on the endpoint type:

• For a native endpoint (Triggered Task or Ultra Task), APIM 3.0 resolves the endpoint Path (substituting path-parameter values) and sends it as PATH_INFO. This is the default behavior as of release 4.45 — you only need to populate Upstream Path when the pipeline should receive a different path than the one matched.
• For an external endpoint, APIM 3.0 sends the request to the endpoint's Upstream URL and appends any trailing request segments. APIM 3.0 does not substitute the route Path into the outbound URL. For example, if Upstream URL is https://api.github.com/repos/acme/widgets/issues, Path is /issues, and Upstream Path is empty, APIM 3.0 forwards a request to /issues/42 as https://api.github.com/repos/acme/widgets/issues/42. Only the trailing /42 is appended; the matched Path /issues is not part of the outbound URL.

Migrating from APIM Classic

If you're not migrating from APIM Classic, you can skip this section.

APIM Classic (Proxies) and APIM 3.0 use different constructs for conditional routing:

• In Classic APIM Manager, each Mapping Rule has conditions that determine when it applies and a Target URL that determines what reaches the upstream.
• In APIM 3.0, advanced routing — Rules or Expression — lives inside an endpoint Path. Migrating a Proxy with Mapping Rules adds the equivalent Rules or Expression on the corresponding Path.

Mapping expressions in Classic often reference path segments by position, such as request.uri.pathSegments[3]. These references can behave unexpectedly after migration because for native endpoints, the path that reaches the pipeline is now PATH_INFO, derived from the endpoint Path (or Upstream Path, if set).

Refer to Move from Classic APIM to APIM 3.0 for migration considerations.