Path matching

When a server receives a request, it must determine which endpoint might potentially handle it. In order to do so, the endpoints are first pre-filtered, so that only endpoints where the path shape matches (that is, the number of path inputs/segments must match, as well as any constant segments) are considered.

Next, the inputs are decoded, starting from the method. If the method inputs decode successfully, the path inputs are decoded.

Exact matches and trailing slashes

The path must match exactly - any remaining path segments will cause the endpoint not to match the request. However, extra trailing slashes are allowed. For example,"api") will match /api, /api/, but won’t match /, /api/users.

To match only the root path, use an empty string:"") will match and

Matching any path

As with all other types of inputs, if no path input/path segments are defined, any path will match.

To match a path prefix, first define inputs which match the path prefix, and then capture any remaining part using paths, e.g.:"api" / "download").in(paths).

Decoding failures

If decoding a path input fails, a 400 Bad Request will be returned to the user. When using the default decode failure handler, this can be customised to instead attempt decoding the next endpoint, by adding an attribute to the path input with .onDecodeFailureNextEndpoint.

Alternatively, another strategy can be implemented by using a completely custom decode failure handler. Both topics are covered in more detail in the documentation of error handling.

Endpoint ordering

The order in which endpoints are given to the server interpreter matters. If the shape of multiple endpoints matches certain requests, such endpoints should be listed from the most specific, to the least specific.

For example, an endpoint"users" / "find") is more specific than"users" / path[Int]("id")), and should be listed first: otherwise attempting to decode "find" as an integer will cause an error. More complex scenarios of path matching can be implemented using the approach described in the previous section.

Security and regular inputs

Any security inputs are decoded first, before regular inputs. Hence, it is not uncommon for the security inputs to define the path prefix of the endpoint, along with any components that the security input should capture.

As noted in the section on security inputs, it is completely fine for the security inputs to contain any kind of inputs, including path segment and path captures. The security/regular distinction only influences the decoding order, and which parameters are available to which part of the server logic.