[DOCS] Reformat index API.

[debadair]

This PR updates the doc index API to align with the new API reference template.

Relates to elastic/docs#937 and #45365

A few questions wrt applying the API Ref template and terminology:

• How are we handling cases where particular path params are mutually exclusive? For example, the typical usage is PUT /<index>/_doc/<_id>, but you can specify PUT /<index>/_create/<_id> to get the put if absent behavior.
• Related, how do we talk about _whatever params--as "endpoints", paths, something else?
• How do we want to refer to the doc _id? Always as _id, ID, doc ID, doc _id?

[elasticmachine]

Pinging @elastic/es-docs

[elasticmachine]

Pinging @elastic/es-distributed

[jrodewig]

How are we handling cases where particular path params are mutually exclusive? For example, the typical usage is PUT //_doc/<_id>, but you can specify PUT //_create/<_id> to get the put if absent behavior.

I would document both endpoints in the Request section. You can note mutually exclusive path params in the param definitions. You can also note this in the long-form Description section.

Related, how do we talk about _whatever params--as "endpoints", paths, something else?

If you need to refer to them, "resource" would be the most common term. "Endpoint" usually refers to the entire URL.

How do we want to refer to the doc _id? Always as _id, ID, doc ID, doc _id?

I think _id is appropriate here as that's also the meta field used to return document IDs. We can use document ID if we're referring to the value, not the field or param.

[jrodewig]

LGTM. Left a few comments, but nothing blocking.

[debadair]

Fixed the broken link with: elastic/elasticsearch-hadoop#1331