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: [email protected]
For additional commands, e-mail: [email protected]
