[
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
In the guide (commit 56ec140) *36 calls on 14 pages* have a working v2 endpoint
whose form is not planned to change, while the page shows only the v1 call
(table below). These can get a v2 tab now.
Calls whose v2 form is still being changed or has not been decided (config
writes, {{update/json}} and {{update/csv}} as one {{/update}}, copy-field,
{{CLUSTERSTATUS}}, metrics, replication, bulk schema, and similar) are out of
scope here and can follow once the form is settled. The plain {{/select}} and
{{/query}} search examples are left as they are.
h3. Proposal
Add the V1/V2 tabs the rest of the guide already uses to these 36 calls, with
strict JSON bodies and the curl style from SOLR-18460. 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.
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:
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}}
> 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
> In the guide (commit 56ec140) *36 calls on 14 pages* have a working v2
> endpoint whose form is not planned to change, while the page shows only the
> v1 call (table below). These can get a v2 tab now.
> Calls whose v2 form is still being changed or has not been decided (config
> writes, {{update/json}} and {{update/csv}} as one {{/update}}, copy-field,
> {{CLUSTERSTATUS}}, metrics, replication, bulk schema, and similar) are out of
> scope here and can follow once the form is settled. The plain {{/select}} and
> {{/query}} search examples are left as they are.
> h3. Proposal
> Add the V1/V2 tabs the rest of the guide already uses to these 36 calls, with
> strict JSON bodies and the curl style from SOLR-18460. 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.
> 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]
