[DOC] Confusion about Index alias API documentation location

[lukas-vlcek]

What do you want to do?

• [x] Request a change to existing documentation
• [ ] Add new documentation
• [ ] Report a technical problem with the documentation
• [ ] Other

Tell us about your request. Provide a summary of the request and all versions that are affected.

When it comes to index alias documentation I was always confused about why it is documented on several places but it is missing under the Index APIs (under the "API REFERENCE"): https://opensearch.org/docs/latest/api-reference/index-apis/index/

First, there is a top level Alias documentation in the API REFERENCE: https://opensearch.org/docs/latest/api-reference/alias/. I think this is confusing because the alias concept is relevant only to the index object. Having a general sounding "Alias" item in the top level REFERENCE API sounds like this can be more general concept available in the OpenSearch. But in reality it is specific to indices only (putting aside a field-alias which is different "Alias thing").

Further, the top level "Alias" documentation points to the "Index alias" documentation: https://opensearch.org/docs/latest/im-plugin/index-alias/ which is located in separate top level section "MANAGING INDICES". This section contains unexpected URL part reading "im-plugin", and while some sections clearly seem to be relevant to ISM-plugin it is not the case for Index aliases(*). In other words, index aliases do not require any plugin to be installed.

(*) And this apply to Index templates as well IMO.

(BTW, why Managing Indices https://opensearch.org/docs/latest/im-plugin/index/ page display a big yellow label "OPENSEARCH DASHBOARDS" in the beginning? It does not sound to me like anything on that page requires Dashboards.)

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.

[hdhalter]

Thanks, Lukas! Aria will take a look at this.

[hdhalter]

Hi Lukas, I looked at this today. Very interesting. I will get it sorted out! In the meantime, I've made the change to remove that Dashboards label from a few different topics. It is a legacy thing that we've managed to ignore until now. Thanks!

[hdhalter]

Hi @kolchfa-aws - can you please take a look at this issue to see if we've addressed all the remarks? I know we've made a number of changes to the indexing topics. Thanks!

[hdhalter]

@lukas-vlcek - Can we close this issue? Otherwise, let me know if there's anything else that should be updated. Thanks!

[lukas-vlcek]

@hdhalter I think we can close it, thanks!