Fix: GET _mapping with index in query.

[dblock]

Description

OpenSearch supports GET _mapping?index=.... If you specify it both on the path and query the query is ignored.

$ curl -u admin:$OPENSEARCH_PASSWORD -k https://localhost:9200/_mapping?index=games | jq

{
  "games": {
    "mappings": {}
  }
}

$ curl --silent -u admin:$OPENSEARCH_PASSWORD -k https://localhost:9200/games/_mapping?index=foobars | jq
{
  "games": {
    "mappings": {}
  }
}

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

Changes Analysis

Commit SHA: 829bbd8
Comparing To SHA: 667091c

API Changes

Summary

├─┬Paths
│ ├─┬/{index}/_mapping
│ │ └─┬GET
│ │   └─┬Parameters
│ │     └──[🔀] in (16587:11)❌ 
│ └─┬/_mapping
│   └─┬GET
│     └──[➕] parameters (16588:13)❌ 
└─┬Components
  └──[➕] parameters (16587:7)

Document Element	Total Changes	Breaking Changes
paths	2	2
components	1	0

• ❌ BREAKING Changes: 2 out of 3
• Modifications: 1
• Additions: 2
• Breaking Modifications: 1
• Breaking Additions: 1

Report

The full API changes report is available at: https://github.com/opensearch-project/opensearch-api-specification/actions/runs/9899446155/artifacts/1693094826

API Coverage

	Before	After	Δ
Covered (%)	483 (47.31 %)	483 (47.31 %)	0 (0 %)
Uncovered (%)	538 (52.69 %)	538 (52.69 %)	0 (0 %)
Unknown	24	24	0

[Xtansia]

Renaming this will cause issues for client generation, as these two are already treated as the same operation merely picking between the paths based on index being specified or not

[dblock]

How should I solve this? The two APIs have effectively different parameters, as the _mapping API takes an index query parameter and the {index}/_mapping API does not. The linter complains that the two must have the same parameters.

[Xtansia]

.NET's logic is that it unions all parameters from all variants and just prefers using the path over the query string if two parameters with the same name but different locations exist. Maybe we could loosen the linter slightly to just validate the variants have the same set of named parameters regardless of location?

Is there any reason to ever use this query string variant over the path variant?

[dblock]

No reason, but the API supports it. We could of course not document it, but 🤷‍♂️

WDYT @nhtruong?

[nhtruong]

@dblock Our clients support optional path parameters. Operations of the same group are only required to share an identical set of querystring params. The only requirement for path params is that if 2 operations have some overlapping path params, then those params must be identical.

[nhtruong]

The Clients Generator Guide touched on this:

If two operations have identical HTTP methods, but different paths: use the path that best matches the path parameters provided.

[nhtruong]

How should I solve this? The two APIs have effectively different parameters, as the _mapping API takes an index query parameter and the {index}/_mapping API does not. The linter complains that the two must have the same parameters.

The clients prioritize path parameters. If index is provided in the clients.indices.get_mapping({ index: 'books' }) then index will be extracted as a path param, and /{index}/_mapping will be used.

From the user's standpoint, there's not distinction between path params and query params. They are all params, including body.

[dblock]

Ended up just adding it to possible query parameters, thanks both!

[nhtruong]

@Xtansia The clients gen will need to account for this situation when there are path and query params that share the same names. Especially for method documentation and typing for the params object. Should we also enforce that params of the same name, regardless of whether they are path or query, should have identical description and schema?

[nhtruong]

I missed this. it should have been false

[dblock]

Yikes