Further clarifying statement for api-name

[gmuratk]

Problem description

API Design Guidelines give a clear statement on api-name. api-name is the API name specified as the base path, prior to the API version, in the servers[*].url property. For example, from /location-verification/v0, it would be location-verification.

However, since 'servers' field is an array of Server Object, there could be more than one servers[*].url property. An API provider may use different strings in each of the Server Objects resolving to different api-name.

Expected action

Update API Design Guideline to ensure same 'api-name' resolution even if there are multiple server objects defined.

Additional context

[hdamker]

@gmuratk My understanding of the design guideline is that the same string is used within the server object and scope names during the API design, both are fixed defined within the API definitions. E.g. the server object is defined as:

servers:
  - url: {apiRoot}/quality-on-demand/v2
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`

which means an API provider shall only differentiate the {apiRoot} but not the last part of the URL with API name and version.

[gmuratk]

@hdamker I agree. The clarification I suggest is to remove any assumptions. This issue is raised based on a question we have received from a developer, and I pointed to the DG, with a similar description you provided.

However, I think just having a statement like the following can avoid questions: If more than one server object instances are listed, each servers[*].url property must have the same string for the API name and version in respective instance

[jlurien]

It makes sense if it helps for clarification