Ordering of matches when no path is concrete

[JonnySpruce]

I'm a contributor for an OpenAPI Validator project, and one of our users has raised an issue that their the spec is not matching in the order they would expect (you can see the issue here).

The issue effectively boils down to the user expecting a path with just one templated segment to be matched over a path with more than one templated segment, i.e.:

/{id1}/{id2}/{id3}
/resource/{id}/new <- Expect this one to be picked

With a request path like: /resource/1/new.

Currently we are matching simply based on the order of the paths as defined by the user in their specification file (which is probably not the correct approach). My question is whether it is specified anywhere how to resolve/match multiple templated matches?

Looking at the relevant part of the OpenAPI3 spec, while it discusses preferring a concrete path over a path which uses templates, from the spec I couldn't see how paths would be chosen if both match the request, and both use templates in the path. Since the examples in the spec are fairly short, I wasn't sure if the above example would fall into the ambiguous category or not.

I did manage to find a discussion in your issues here which hints at the fact most people would match a path with more concrete segments, over one with less. Since we are a validation tool, I would prefer to be able to apply concrete rules.

Do you have any advice/further reading on matching paths like the above example?

[rwalle61]

Any comments on this?

Basically, if a request is made with path /foo/bar, and an OpenAPI document has these 2 paths,

/{a}/{b}
/foo/{c}

which OpenAPI path does the request match? (Or is it ambiguous, like one of these examples from the official OpenAPI Specification?)

Thanks!

[rwalle61]

Thanks for adding the Review tag to this, did it get discussed at the review meeting?

[jchook]

...from the spec I couldn't see how paths would be chosen if both match the request, and both use templates in the path.

Your example may violate this stipulation:

Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical

If it doesn't, it may help to expand that "MUST NOT" to avoid other types of ambiguity.

Example 1

• /resource/{id}
• /resource/new

This seems ambiguous, even with smart matching. What if you used short codes for IDs and had a resource with id = new?

Example 2

• /resource/edit/{id}
• /resource/{id}/view

Does this count as "two templated paths with the same hierarchy but different templated names"? What does "same hierarchy" mean?

Example 3

• /resource/new
• /resource/x-{id}

Can you do partially templated path segments like this? If so, that may further complicate matters (see #1970).

Example 4

• /resource/new
• /resource/view/{id}

This solves the matching ambiguity problem in the other 3 examples simply by avoiding path ambiguity altogether.

[jchook]

It seems that, even though we can conceive of tricky ways to resolve various types of ambiguity, avoiding it entirely would strengthen the rigorousness of the spec, ensure better interoperability of community tools, simpler/easier implementations, and ultimately simpler/faster routing.

[rwalle61]

Thanks @jchook, yea I agree that whatever the decision, users should avoid defining paths in their OpenAPI specs that are close to such ambiguity.

Still, a user of our dev tool wants to do it anyway, so it'd be good to know which of the 2 paths we should officially match. I.e., what is the official definition of paths with "same hierarchy"?

Re the 4 examples, I believe Example 1 is covered by

When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts.

So the concrete path would be matched.

As you say, there's no ambiguity in example 4.

I guess example 3 would be two paths of "same hierarchy", like the example in the spec of 2 paths that are too similar (although yes it's unclear)

Example 2 is spot on - are the two paths of "same hierarchy"?