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, endpoint.in("api") will match /api, /api/, but won’t match /, /api/users.

To match only the root path, use an empty string: endpoint.in("") will match http://server.com/ and http://server.com.

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.: endpoint.in("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 endpoint.in("users" / "find") is more specific than endpoint.in("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.