[jira] [Created] (SOLR-18491) Ref Guide: show a v2 form wherever only v1 is shown

["Serhiy Bzhezytskyy (Jira)" <ji...@apache.org>]

Serhiy Bzhezytskyy created SOLR-18491:
-----------------------------------------

             Summary: Ref Guide: show a v2 form wherever only v1 is shown
                 Key: SOLR-18491
                 URL: https://issues.apache.org/jira/browse/SOLR-18491
             Project: Solr
          Issue Type: Sub-task
          Components: documentation
            Reporter: Serhiy Bzhezytskyy


Many pages of the Ref Guide show an API call only in its v1 form (`/solr/admin/...`, `/solr/{collection}/...`), even though a v2 endpoint for it exists and works. A reader who wants to use the v2 API cannot find out how from the guide, and the v2 API is where the project is heading (SOLR-18459, SOLR-18469).

To see how big the gap is, I went through every API call in the guide (commit 56ec140): 535 v1 calls, 408 with no v2 form in their own section. I compared each with the "Solr v2 API Proposed Changes" sheet (current vs proposed form) and with a running node:

* 172 are `/select` and `/query` search examples with a v2 route. A v2 tab on every search example is a style question, so I'd leave them for now.
* 38, on 15 pages, have a v2 route and the same form in the sheet as current and proposed. I ran the v2 form of each on a live node: 36 work (some with sample data in place of the page's fictional fields or configsets). These can get a v2 tab now.
* 34 have a v2 route, but the sheet proposes a different form (config writes, `update/json` and `update/csv` as one `/update` by Content-Type, copy-field, some collection and core commands). Those wait for the migration.
* 60 have a working v2 route that the sheet leaves open or doesn't list (plain `/update`, whose proposal is marked `???`, writes to `config/params`, `CLUSTERSTATUS`, metrics, replication, `terms`, bulk schema).
* 67 have no v2 route (managed resources like stopwords and synonyms, `/stream`, `/sql`, `/admin/luke`, `update/json/docs`). These are a gap in the API rather than in the guide and stay v1-only.
* 37 are not verified (the handler is not configured in the test collection).

What I'd like to do: add the V1/V2 tabs the rest of the guide already uses to the 36 that are ready, with strict JSON bodies and the curl style from SOLR-18460, and run each v2 example on a node before it goes in. Pages that are being changed by other work (the curl-style cleanup, the schema API and the authorization API) would come last, so that the tabs are not written twice. The 60 can follow once someone confirms the form.

The 38 per page, with the v2 API the page does not show:

|| page || v2 API missing from the page ||
| exporting-result-sets | `GET /api/collections/{c}/export` (3 examples) |
| schemaless-mode | `GET /api/collections/{c}/schema/fields`, `PUT`/`DELETE` for fields, field types and dynamic fields, `GET …/schema/copyfields` |
| schema-api | `GET /api/collections/{c}/schema`, `PUT …/schema/fields/{name}`, `POST …/schema/bulk` |
| tutorial-films | `POST /api/collections`, `PUT …/schema/fields/{name}`, `POST …/schema/bulk` |
| tutorial-opennlp, tutorial-paramsets, tutorial-vectors | `PUT …/schema/fields/{name}`, `POST …/schema/bulk` |
| solr-in-docker | `POST /api/collections` |
| alias-management | `POST /api/aliases` |
| coreadmin-api | `POST /api/cores` † |
| cluster-node-management | `PUT /api/cluster/properties/{name}`, `POST /api/collections/{c}/balance-shard-unique`, `GET /api/cluster/overseer` |
| replica-management | `POST …/shards/{s}/replicas`, `PUT …/replicas/{r}/properties/{p}` (4 examples) |
| collection-management | backups: `GET /api/backups/{b}/versions`, `POST …/restore`, `DELETE …/versions/{id}`, `DELETE …/versions?maxNumBackupPoints=` †, `PUT …/purgeUnused` |
| rule-based-authorization-plugin | `POST /api/cluster/security/authorization` (5 examples) |
| jwt-authentication-plugin | `GET /api/node/system` |

† held back for now; the other 36 are ready.




--
This message was sent by Atlassian Jira
(v8.20.10#820010)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org