How to handle ambiguous paths in the API spec

[iuliag]

Overview

How to handle ambiguous paths in the API spec?

As seen in the docs linting warnings when running npm run docs, we have some ambiguous/conflicting paths.
Example:

Paths should resolve unambiguously. Found two ambiguous paths: `/sites/by-delivery-type/{deliveryType}` and `/sites/{siteId}/experiments`.

In some cases, it's clear that the static path segments like by-delivery-type,experiements etc. don't match with the format requirements of the path parameters like siteId (uuid), deliveryType (enum).

But it's still confusing and error prone, as routes have to be ordered top down from the most specific to the more dynamic in the API implementation, in order to have the proper behavior of the API implemented.

Details

OpenAPI spec v3.1.1 https://spec.openapis.org/oas/v3.1.1.html#patterned-fields mentions:

4.8.8.1 Patterned Fields

Field Pattern	Type	Description
/{path}	Path Item Object	A relative path to an individual endpoint. The field name MUST begin with a forward slash (/). The path is appended (no relative URL resolution) to the expanded URL from the Server Object’s url field in order to construct the full URL. Path templating is allowed. 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.

4.8.8.2 Path Templating Matching
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}

Proposed Actions

Come up with a recommendation so that we can avoid ambiguous paths in the future from the API design phase.

[iuliag]

cc: @solaris007, @chicharr

[TulsiLukhi1]

Hey team,

I don't have much exposure to this project yet, but I was thinking about the ambiguous path issue mentioned here.

It seems like the problem is mostly about how paths with dynamic parameters (like {siteId} and {deliveryType}) are being interpreted by the linter. My guess is that if we can apply parameter constraints (e.g., enum or pattern), it might help in distinguishing between these dynamic parameters more clearly.

It really depends on how restrictive the linter is, but if we can set specific constraints for the dynamic parameters (like applying UUID format to {siteId} and a set of predefined values to {deliveryType}), the linter should be able to differentiate between the paths and resolve the ambiguity.

paths:
  /sites/{siteId}/experiments:
    parameters:
      - name: siteId
        in: path
        required: true
        schema:
          type: string
          pattern: '^[a-f0-9-]{36}$'  # Ensures this is a UUID

  /sites/by-delivery-type/{deliveryType}:
    parameters:
      - name: deliveryType
        in: path
        required: true
        schema:
          type: string
          enum: ['standard', 'express']  # Limits deliveryType to standard or express

This YAML file I referred to is part of the OpenAPI specification, which is commonly used to define RESTful API endpoints and their behaviors so for this project, yaml file we can change this accordingly.

so Linter would identify a different path like this,
For /sites/{siteId}/experiments, the UUID pattern (^[a-f0-9-]{36}$) ensures that the {siteId} must be in UUID format, which is a very specific format. This helps the linter understand that this path cannot match a {deliveryType}, which would be a string like "express" or "standard."

For /sites/by-delivery-type/{deliveryType}, the enum (['standard', 'express']) restricts the possible values for {deliveryType} to only two options. This makes it clear that this parameter can never be confused with a {siteId}, which follows a different format.

This might work!
And if I am going wrong, please guide me as I am new here!