[DOC] Add missing Core REST API endpoints

[Naarcha-AWS]

Because the OpenSearch REST API documentation is no longer automated, we need to create a feature complete API reference, one the includes all endpoints, request bodies, and responses.

For reference on what ideal REST API reference page looks like, see the OpenSearch Create Index API.

List of missing endpoints

To assist in achieving this goal, I've put together a list of APIs that are missing, based on cross-referencing the old Open Distro API reference. NOTE: This list is not comprehensive and might not include all missing endpoints.

• mget
• nodes.hot_threads
• nodes.info
• node.reload - Need to document this (only available in OpenDistro doc)
• nodes.stats Adds nodes stats API #1369
• nodes.usage - Need to document this (only available in OpenDistro doc)
• put.script
• rank.eval
• snapshot.cleanup
• snapshot.clone
• snapshot.create | PR add files for snapshot creation #873
• snapshot.create_repository
• snapshot.delete
• snapshot.delete_repository
• snapshot.get
• snapshot.get_repository
• snapshot.restore
• snapshot.status
• snapshot.verify_repository
• GET _scripts/<script-id> | Add script documentation. #1016
• PUT _scripts/<script-id> | Add script documentation. #1016
• PUT _scripts/<script-id>/<context> | Add script documentation. #1016
• DELETE _scripts/<script-id> | Add script documentation. #1016
• GET _script_context | Add script documentation. #1016
• GET _script_language | Add script documentation. #1016
• POST /_scripts/painless/_execute | Add script documentation. #1016
• POST /<target>/_reload_search_analyzers | Not in code base
• GET /<target>/_reload_search_analyzers | Not in code base
• GET /_analyze https://github.com/opensearch-project/documentation-website/pull/1373/files
• POST /_analyze https://github.com/opensearch-project/documentation-website/pull/1373/files
• GET /<index>/_analyzeAdd documentation for reload_searchIanalyzer api #1339
• POST /<index>/_analyze Add documentation for reload_searchIanalyzer api #1339
• POST /<target>/_cache/clear Add the two clear cache APIs #1168
• POST /_cache/clear Add the two clear cache APIs #1168
• DELETE /_dangling/<index-uuid> Adding documentation for dangling index api #1370
• POST /_dangling/<index-uuid> Adding documentation for dangling index api #1370
• ism_rollup Add ism rollup to documentation #1371

After the request and responses have been documented, please check off the API from this list.

Test API

1. Install OpenSearch. We recommend using Docker with the a sample Docker compose file that disables the security plugin.
2. After installation, run OpenSearch and log into Dashboards.
3. Find the API test console. There, enter each API endpoint listed above with the correct request body. Upon successful execution, the response appears on the right column.

Time to complete

Each API endpoint should only take about 4 - 5 hours to test, document, and address any review feedback required. With 19 found undocumented endpoints, this assumes an average time to complete of 12 - 15 days.

[Naarcha-AWS]

Looking at this issue and thinking, "That endpoint is already documented!" or "What about this endpoint?". Leave a comment and we'll add or remove endpoints to the list.

[bgdnlp]

As per #176, I think ingest pipelines are an undervalued feature that seems to be little known. Would it be possible to add some clear and straight forward documentation about it?

I'm talking about ingest pipelines and APIs.

I wasn't able to find any dedicated pages for that. There are some references, for example in the _reindex section, but there's no chapter that I could find that explains ingest pipeline or nodes, their role, and how it can replace Logstash for example. Which seems very useful to me, but I'm definitely no expert.

[lukas-vlcek]

@bgdnlp I think there is basic documentation about Ingest APIs but I agree it is missing more detailed information including list of available ingest processors and their doc. (And yes I agree that ingest pipelines is a cool feature!)

[bgdnlp]

To add more details, in case it helps, what I'd like to see as a newcomer is

• A page describing ingestion pipelines and how they can be an alternative to Logstash (I believe). Something like ElasticSearch docs. Maybe even some kind of howto like the AWS blog post where I first found out about this feature.
• A mention and links to the above in the docs, wherever ingestion methods are presented, like here.
• A comparison with Logstash. I know that Logstash is more feature rich and moving processing to nodes obviously can have consequences, but for simpler use cases not having to manage Logstash seems like a net win to me, so I'm not sure why it's not presented as an alternative. For example, the AWS page on data ingestion doesn't even mention it, neither does the FAQ. Which makes me think that maybe it's never a good choice.

What I mean is that if I didn't already know about it, if I looked at the documentation around OpenSearch as a newcomer I don't think I'd find it. ElasticSearch, yes, probably. But in OpenSearch it seems to be completely ignored for some reason. I hope it helps.

[oridool]

what about the missing snapshot endpoints ?
Specifically, can we use URL parameters in GET endpoint such as sort and from_sort_value mentioned here? https://www.elastic.co/guide/en/elasticsearch/reference/current/get-snapshot-api.html

[Naarcha-AWS]

@Steve-O-Murphy: Thanks for coming on board, Steve. Here is the list Rest APIs we'll get started:

• snapshot.create
• snapshot.create_repository
• snapshot.delete
• snapshot.delete_repository
• snapshot.get
• snapshot.get_repository

[cwillum]

API to enable audit logs is in process. #746.

• GET _plugins/_security/api/audit
• PUT _plugins/_security/api/audit/config
• PATCH _plugins/_security/api/audit