Match Path Params In APIs

A mock API often needs to handle the same route for many different IDs, such as /api/users/123 and /api/users/234. Beeceptor can match these requests with a path template and make the changing values available in the response. You can also use regular expressions when a route needs a specific pattern, such as a numeric ID.

Named Parameters

You can define the fixed parts of your route and give each dynamic segment a name prefixed with a colon. For example, the template /api/users/:userId matches both /api/users/123 and /api/users/234, capturing 123 or 234 as userId. These values are commonly called route parameters or path variables, as in routing systems such as Django, Spring Boot, and Express.

Create a mock rule and use a request path template as the matching condition. A route can contain several named parameters:

/orders/:orderId/items/:itemId

For a request to /orders/AB-9987/items/2, Beeceptor extracts orderId as AB-9987 and itemId as 2. One rule can therefore handle different orders and items.

Route Parameter Matching With Request Path

A template must start with /, contain at least one named parameter, and exclude ? and #. Trailing slashes are ignored: /api/users/:userId matches both /api/users/123 and /api/users/123/.

Using In The Response

Enable Enable dynamic mock responses in the rule, then use the pathParam helper to insert a captured value into your response template. For the order and item template above, set the response body to:

{
  "orderId": "{{pathParam 'orderId'}}",
  "itemId": "{{pathParam 'itemId'}}"
}

A request to /orders/AB-9987/items/2 returns:

{
  "orderId": "AB-9987",
  "itemId": "2"
}

Beeceptor URL-decodes each extracted parameter before making it available to response templating. For example, /api/users/Jane%20Doe matched against /api/users/:userId makes Jane Doe available through {{pathParam 'userId'}}.

Regular Expressions

Beeceptor's regular expression allows you to match complex request paths, and enable extracting parts of the request path as variables. To use this, create a mock rule that specifies a regular expression as the criterion for matching the request path. Now in the expression textbox, provide the regular expression.

Example: For a mock rule aimed at matching user IDs in a request path, you should use the following regular expression:

/api/users/\d+

This expression matches a sequence of one or more digits for the user entity.

This rule setup matches to all request paths having the format:
https://my-endpoint.proxy.beeceptor.com/api/users/1234

Named Groups

With Beeceptor, you can go further, and include named groups to capture specific segments of the path for later use in the response. These are extracted as variables and available in the response template. This approach provides a flexible way to craft dynamic responses based on the incoming request's specifics. Let's see it in action.

Example: The following regular expression uses a named group. The sequence of one or more digits is named as userID and available as a variable in response.

/api/users/(?<userID>\d+)

For the complete setup of this rule refer below screenshot. Make sure to select the 'Enable dynamic mock responses' checkbox to enable the template engine.

This rule setup matches to all request-paths having below format and extracts the entity-id:
https://my-endpoint.proxy.beeceptor.com/api/users/1234

Now when you hit the API URL as https://my-endpoint.proxy.beeceptor.com/api/users/234, you get the following response. Here, the id value is picked from the request path.

{
     "id" : "234",
     "name": "David"
}

Use {{pathParam 'userID'}} in the response template to read the value captured by the named group.