Are those OpenAPI 3 paths ambiguous?

Viewed 317

Are those OpenAPI 3 paths ambiguous?

/shops/{shopId}/pets/{petId}   
/shops/{shopId}/pets/_search

I want to answer no but, strictly reading the spec, I can't decide because they seem to fall into none of the 3 statements made by the spec:

  1. Neither path is concrete (term used in the spec)
  2. Paths don't seem to meet the Templated paths with the same hierarchy but different templated names criteria (that is not very clear to me): "/shops/{}/pets/{}" != "/shops/{}/pets/_search "
  3. Paths do not look like the ambiguous example

Below is an excerpt of the OA3 spec (and nothing more: my question is on the first line).

Excerpt of the OA3 spec

The "Paths object" paragraph of the OpenAPI 3 specification (https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#paths-object) is stating (3 sentences, 3 statements):

When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.

Those 3 statements are followed by 3 examples (and that's it):

Assuming the following paths, the concrete definition, /pets/mine, will be matched first if used:

/pets/{petId}
/pets/mine

The following paths are considered identical and invalid:

/pets/{petId}
/pets/{name}

The following may lead to ambiguous resolution:

/{entity}/me
/books/{id}

1 Answers

My reading of the spec is that they are not ambiguous, because one is more concrete than the other. The more concrete one takes precedence if the {petId} parameter value is set to _search.

Related