--- title: Use Path Variables slug: use-path-variables type: how-to plugin: huxx-connect summary: Put {0} or {product_id} variables in an endpoint path and fill them at request time with endpoint_variables. keywords: [path variables, endpoint variables, dynamic url, indexed, named] version_added: 1.2.5 version_updated: 1.2.5 level: intermediate related: [send-query-header-and-body-parameters, display-data-with-shortcodes, use-template-functions, debug-api-requests] --- Path variables let one [endpoint](/docs/connect/explanation/glossary/#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: `[huxx_api api_id="demo_api" endpoint_id="product_detail" endpoint_variables="1"]` > - 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. :::novice 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](/docs/connect/explanation/glossary/#api). See [How HuxxConnect works](/docs/connect/explanation/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. ``` [huxx_api api_id="demo_api" endpoint_id="product_detail" endpoint_variables="product_id=1" keys="title"] ``` Output: ``` Essence Mascara Lash Princess ``` **PHP** — pass an array under `endpoint_variables`. Indexed array for indexed paths, associative for named paths: ```php $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](/docs/connect/how-to/debug-api-requests/). ### 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](/docs/connect/how-to/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.