Skip to main content
Version: Next

Path Parameters Configuration

Path parameters allow you to create flexible and reusable URL patterns by defining variable segments within the URL. This enables you to group similar endpoints and apply consistent policies across them.

Why Use Path Parameters?​

Path parameters are particularly useful when you have multiple variations of an endpoint that follow a similar pattern, want to apply the same policies to endpoints with variable segments, and need to manage a large number of dynamic endpoints efficiently.

By using path parameters, the discover command of the proxy presents a more ordered and grouped view, making endpoint management easier. The UI control plane also reflects this organization, offering a clearer and more manageable interface.

Case Example:​

Consider an API with multiple URLs, each containing different IDs:

api.com/users/123/profile
api.com/users/456/profile
api.com/users/789/profile

Without declaring a path parameter, each URL variation would be treated as a separate entry, leading to more complex policy management. Declaring a path parameter like api.com/users/{userId}/profile consolidates these variations into a single, manageable endpoint, simplifying policy application and improving metrics views.

Defining Path Parameters in {fileName}.yaml​

Configuration Overview​

To configure path parameters in Lunar Flows, create a YAML file {fileName}.yaml and place it in the /etc/lunar-proxy/path_params/ directory. The file structure follows this pattern:

/etc/lunar-proxy/path_params/{fileName}.yaml

For example, if the configuration file is named users_path_params.yaml, it would be stored as:

/etc/lunar-proxy/path_params/users_path_params.yaml
note

File names for Lunar's YAML configurations don't need to follow a specific convention (e.g., users_path_params.yaml). As long as the file is placed in the correct folder, Lunar will automatically detect and apply it.

Example Configuration​

/etc/lunar-proxy/path_params/{fileName}.yaml
path_params:
  - url: httpbin.org/anything/{param1}/{param2}
  - url: httpbin.org/get/{param1}

This configuration creates path parameters that can capture dynamic segments of the URL, such as param1 and param2, making it easier to apply policies or gather metrics across various similar endpoints.

Key Rules and Restrictions​

  • Unique Path Definitions: If a URL exists in more than one path parameter definition, the engine will raise an error. This is to avoid conflicts such as:

    httpbin.org/get/{param1}
    httpbin.org/get/{myParam}

    In this case, the engine cannot resolve which parameter to use, so you must ensure that path parameters are unique.

  • Single Declaration: A path parameter can only be declared in one location. It can either be configured in path_params.yaml or within flow.yaml or quota.yaml, but not in both. This prevents conflicts and ensures clear, consistent configuration management.

caution

Consistency in Parameter Names When configuring a path parameter in path_params.yaml, ensure that the exact same parameter name is used in any associated flow configurations within flow.yaml. For example, if path_params.yaml includes api.example.com/{param1}, the flow configuration in flow.yaml must also reference api.example.com/{param1} (and not a different parameter name like {param2}). Misalignment between these files, such as configuring {param1} in path_params.yaml and {param2} in flow.yaml, will cause a collision that prevents the gateway and flows from functioning properly.