OAI / OAI/OpenAPI-Specification
Ordering of matches when no path is concrete
Nobody has claimed this yet.
- Dominant language
- Markdown
- Stars
- 31.2k
- Forks
- 9.2k
- Avg merge
- 6h 37m
- Merged PRs (30d)
- 27
Description
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?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked OpenAPI 3.0.3 Patterned Fields section and the discussion in OpenAPI Specification issue #1459. Compare their guidance with the templated-path example in this issue and determine whether a normative ordering rule exists. Done means the ambiguity is resolved with a documented rule or a clear statement that the specification does not define one.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100