Skip to Main
View .mdAsk ClaudeAsk ChatGPT

Path variables let one endpoint serve many URLs. Instead of creating a separate endpoint for every product ID, you write the path once — /products/{0} — and supply the ID when you make the request.

Quick version:

  1. In the endpoint’s Path field, write {0}, {1} for positional variables or {product_id} for named ones. Never both in one path.
  2. Pass values at runtime via endpoint_variables:
    • Shortcode:
    • PHP: huxx_api( 'demo_api', 'product_detail', [ 'endpoint_variables' => [ 1 ] ] );
  3. Named form: endpoint_variables="product_id=1" / [ 'endpoint_variables' => [ 'product_id' => 1 ] ].

Choose a variable style

HuxxConnect supports two styles of path variable:

  • Indexed — {0}, {1}, {2}: filled by position from the values you pass.
  • Named — {product_id}, {slug}: filled by key. Names must start with a letter or underscore and may contain letters, digits, and underscores.

Named variables are the better default: endpoint_variables="product_id=1" still reads correctly six months later, while "1" requires you to remember what position 0 meant. Use indexed variables for quick one-slot paths or when migrating configurations that already use them.

New to APIs? Read this first

A URL like https://dummyjson.com/products/1 ends with a specific record’s ID. A path variable is a labeled blank in that URL that you fill in each time you call the API. See How HuxxConnect works for the full request picture.

Add a variable to the endpoint path

Edit the endpoint and set its Path field. The field’s inline hint states the rule: “Should start with a slash. Use {0}, {1} or {post_id}, {name} for dynamic segments. Do not mix styles.”

For the DummyJSON demo API, create an endpoint product_detail with:

  • Method: GET
  • Path: /products/{product_id}

Save the endpoint. You can try values immediately in the endpoint’s test panel — when the path contains variables, a Path Variables input appears there.

The cannot-mix rule

A single path must use one style. /users/{user_id}/posts/{0} is rejected on save with this error:

Path cannot mix indexed ({0}) and named ({post_id}) variables.

The admin UI blocks the save before it is sent, and the endpoint REST routes enforce the same rule server-side (src/Admin/Rest/EndpointController.php) — a request made directly to the REST API gets the same message with an added “Use one style.” sentence. Imports and other non-REST write paths are not covered by this check: an imported file containing a mixed path is stored as-is. At request time a mixed path resolves by direct key-based substitution only — values must be keyed exactly as the variables are written (user_id and 0); positional values leave named variables unreplaced. Convert such a path to one style when you notice it.

Pass values at runtime

Everywhere HuxxConnect accepts runtime arguments, the key is endpoint_variables.

Shortcode — the attribute auto-detects the format: values containing = are parsed as named pairs, otherwise as a comma-separated positional list.

Output:

Essence Mascara Lash Princess

PHP — pass an array under endpoint_variables. Indexed array for indexed paths, associative for named paths:

$product = huxx_api( 'demo_api', 'product_detail', array(
    'endpoint_variables' => array( 'product_id' => 1 ),
) );

echo esc_html( $product['title'] );

Output:

Essence Mascara Lash Princess

In both cases the request URL becomes https://dummyjson.com/products/1. Each value is URL-encoded before substitution, so a value like blue jeans becomes blue%20jeans in the URL — you never encode values yourself.

Advanced

Mismatched styles map by position

If the styles of the path and the supplied values disagree, HuxxConnect falls back to positional mapping instead of failing (src/Http/RequestBuilder.php):

  • Named path + indexed values: /products/{product_id} with [ 1 ] → position 0 fills the first named variable.
  • Indexed path + associative values: /products/{0} with [ 'product_id' => 1 ] → values are taken in order and mapped by position.

This keeps shortcodes working when an endpoint path is later renamed from indexed to named style. Still, matching styles is clearer — treat the fallback as a safety net, not a feature to rely on.

Unfilled variables stay in the URL

A variable you never supply a value for is left as-is: the request goes out with a literal {product_id} in the URL. That is deliberate — the unreplaced variable is visible in the request log, which makes the mistake obvious when you debug the request.

Repeated variables

The same variable may appear more than once (/compare/{product_id}/with/{product_id}); every occurrence gets the same value.

If it didn’t work

The API returned 404 and the logged URL contains {...} literally. The variable was never substituted. For named paths, the keys you pass must match the names in the path exactly (product_id, not productId). Check the exact outgoing URL with Debug API requests.

Saving the endpoint fails with “Path cannot mix indexed ({0}) and named ({post_id}) variables.” The path contains both styles — note that any {word} segment counts as a named variable. Convert everything to one style.

The value arrives mangled at the API. Values are URL-encoded once during substitution. If you pass a pre-encoded value like blue%20jeans, it is encoded again (blue%2520jeans). Pass the raw value and let HuxxConnect encode it.