[
https://issues.apache.org/jira/browse/SOLR-18491?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Serhiy Bzhezytskyy updated SOLR-18491:
--------------------------------------
Description:
h3. Problem
Many pages of the Ref Guide show an API call only in its v1 form
({{/solr/admin/...}}, {{/solr/\{collection\}/...}}), although a working v2
endpoint exists for it. A reader who wants to use the v2 API cannot learn from
the guide how to call it, and v2 is where the project is heading (SOLR-18459,
SOLR-18469).
h3. How big the gap is
I went through every API call in the guide (commit 56ec140). Of about 530 v1
calls, about 300 have a working v2 endpoint that the page does not show. I ran
the v2 form on a live node and compared it with the planned v2 changes:
* *172* are {{/select}} and {{/query}} search examples. A v2 tab on each is a
style question. I ran 126 of them on a test node, each in v1 and in v2: 117
give the same result, none differ.
* *36*, on 14 pages, have a v2 endpoint whose form is not planned to change. I
ran the v2 form of each: all 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 endpoint whose form is planned to change (config writes,
{{update/json}} and {{update/csv}} as one {{/update}} by Content-Type,
copy-field, some collection and core commands). They wait for that migration.
* *66* have a working v2 endpoint whose future form is not settled yet (plain
{{/update}}, writes to {{config/params}}, {{CLUSTERSTATUS}}, {{COLSTATUS}},
metrics, replication, {{terms}}, bulk schema, node and system info).
h3. Proposal
Add the V1/V2 tabs the rest of the guide already uses to the 36, 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) come last, so
that the tabs are not written twice. The 66 can follow once the form is
confirmed.
h3. The 36 calls, by page, with the v2 API each page does not show yet
h4. Query and indexing
*exporting-result-sets (3 examples)*
* {{GET /api/collections/\{c\}/export}}
*schemaless-mode*
* {{GET /api/collections/\{c\}/schema/fields}}
* {{PUT}} / {{DELETE}} for fields, field types and dynamic fields
* {{GET /api/collections/\{c\}/schema/copyfields}}
*schema-api*
* {{GET /api/collections/\{c\}/schema}}
* {{PUT /api/collections/\{c\}/schema/fields/\{name\}}}
* {{POST /api/collections/\{c\}/schema/bulk}}
h4. Getting started
*tutorial-films*
* {{POST /api/collections}}
* {{PUT /api/collections/\{c\}/schema/fields/\{name\}}}
* {{POST /api/collections/\{c\}/schema/bulk}}
*tutorial-opennlp, tutorial-paramsets, tutorial-vectors*
* {{PUT /api/collections/\{c\}/schema/fields/\{name\}}}
* {{POST /api/collections/\{c\}/schema/bulk}}
h4. Collections, replicas and cores
*solr-in-docker*
* {{POST /api/collections}}
*alias-management*
* {{POST /api/aliases}}
*replica-management (5 examples)*
* {{POST /api/collections/\{c\}/shards/\{s\}/replicas}}
* {{PUT /api/collections/\{c\}/shards/\{s\}/replicas/\{r\}/properties/\{p\}}}
(4 examples)
*collection-management (4 examples, backups)*
* {{GET /api/backups/\{b\}/versions}}
* {{POST /api/backups/\{b\}/restore}}
* {{DELETE /api/backups/\{b\}/versions/\{id\}}}
* {{PUT /api/backups/\{b\}/purgeUnused}}
h4. Cluster and security
*cluster-node-management (4 examples)*
* {{PUT /api/cluster/properties/\{name\}}}
* {{POST /api/collections/\{c\}/balance-shard-unique}} (2 examples)
* {{GET /api/cluster/overseer}}
*rule-based-authorization-plugin (5 examples)*
* {{POST /api/cluster/security/authorization}}
*jwt-authentication-plugin*
* {{GET /api/node/system}}
was:
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.
> 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
> Priority: Major
>
> h3. Problem
> Many pages of the Ref Guide show an API call only in its v1 form
> ({{/solr/admin/...}}, {{/solr/\{collection\}/...}}), although a working v2
> endpoint exists for it. A reader who wants to use the v2 API cannot learn
> from the guide how to call it, and v2 is where the project is heading
> (SOLR-18459, SOLR-18469).
> h3. How big the gap is
> I went through every API call in the guide (commit 56ec140). Of about 530 v1
> calls, about 300 have a working v2 endpoint that the page does not show. I
> ran the v2 form on a live node and compared it with the planned v2 changes:
> * *172* are {{/select}} and {{/query}} search examples. A v2 tab on each is a
> style question. I ran 126 of them on a test node, each in v1 and in v2: 117
> give the same result, none differ.
> * *36*, on 14 pages, have a v2 endpoint whose form is not planned to change.
> I ran the v2 form of each: all 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 endpoint whose form is planned to change (config writes,
> {{update/json}} and {{update/csv}} as one {{/update}} by Content-Type,
> copy-field, some collection and core commands). They wait for that migration.
> * *66* have a working v2 endpoint whose future form is not settled yet (plain
> {{/update}}, writes to {{config/params}}, {{CLUSTERSTATUS}}, {{COLSTATUS}},
> metrics, replication, {{terms}}, bulk schema, node and system info).
> h3. Proposal
> Add the V1/V2 tabs the rest of the guide already uses to the 36, 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) come last, so
> that the tabs are not written twice. The 66 can follow once the form is
> confirmed.
> h3. The 36 calls, by page, with the v2 API each page does not show yet
> h4. Query and indexing
> *exporting-result-sets (3 examples)*
> * {{GET /api/collections/\{c\}/export}}
> *schemaless-mode*
> * {{GET /api/collections/\{c\}/schema/fields}}
> * {{PUT}} / {{DELETE}} for fields, field types and dynamic fields
> * {{GET /api/collections/\{c\}/schema/copyfields}}
> *schema-api*
> * {{GET /api/collections/\{c\}/schema}}
> * {{PUT /api/collections/\{c\}/schema/fields/\{name\}}}
> * {{POST /api/collections/\{c\}/schema/bulk}}
> h4. Getting started
> *tutorial-films*
> * {{POST /api/collections}}
> * {{PUT /api/collections/\{c\}/schema/fields/\{name\}}}
> * {{POST /api/collections/\{c\}/schema/bulk}}
> *tutorial-opennlp, tutorial-paramsets, tutorial-vectors*
> * {{PUT /api/collections/\{c\}/schema/fields/\{name\}}}
> * {{POST /api/collections/\{c\}/schema/bulk}}
> h4. Collections, replicas and cores
> *solr-in-docker*
> * {{POST /api/collections}}
> *alias-management*
> * {{POST /api/aliases}}
> *replica-management (5 examples)*
> * {{POST /api/collections/\{c\}/shards/\{s\}/replicas}}
> * {{PUT /api/collections/\{c\}/shards/\{s\}/replicas/\{r\}/properties/\{p\}}}
> (4 examples)
> *collection-management (4 examples, backups)*
> * {{GET /api/backups/\{b\}/versions}}
> * {{POST /api/backups/\{b\}/restore}}
> * {{DELETE /api/backups/\{b\}/versions/\{id\}}}
> * {{PUT /api/backups/\{b\}/purgeUnused}}
> h4. Cluster and security
> *cluster-node-management (4 examples)*
> * {{PUT /api/cluster/properties/\{name\}}}
> * {{POST /api/collections/\{c\}/balance-shard-unique}} (2 examples)
> * {{GET /api/cluster/overseer}}
> *rule-based-authorization-plugin (5 examples)*
> * {{POST /api/cluster/security/authorization}}
> *jwt-authentication-plugin*
> * {{GET /api/node/system}}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
