This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/main by this push:
new cf4a66669d3 SOLR-18499: Drop the _introspect section from the v2 API
page (#5123)
cf4a66669d3 is described below
commit cf4a66669d37a308ac02bfd0211abe1897330df7
Author: Serhiy Bzhezytskyy <[email protected]>
AuthorDate: Tue Oct 13 16:19:43 2026 +0300
SOLR-18499: Drop the _introspect section from the v2 API page (#5123)
---
.../modules/configuration-guide/pages/v2-api.adoc | 104 ++-------------------
1 file changed, 10 insertions(+), 94 deletions(-)
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc
b/solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc
index 6d0e6c0e60d..405c250a957 100644
--- a/solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc
+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/v2-api.adoc
@@ -17,19 +17,18 @@
// under the License.
[[top-v2-api]]
-The v2 API is a modernized self-documenting API interface covering most
current Solr APIs.
+The v2 API is a modernized API interface covering most current Solr APIs.
It is anticipated that once the v2 API reaches full coverage, and
Solr-internal API usages like SolrJ and the Admin UI have been converted from
the old API to the v2 API, the old API will eventually be retired.
Today, the two API styles coexist, and all the old APIs will continue to work
without any change.
NOTE: The v2 API is classified as "experimental".
It may change in backwards-incompatible ways as it evolves to cover additional
functionality.
-The old API and the v2 API differ in three principle ways:
+The old API and the v2 API differ in two principle ways:
. Command format: The old API commands and associated parameters are provided
through URL request parameters on HTTP GET requests, while in the v2 API most
API commands are provided via a JSON body POST'ed to v2 API endpoints.
The v2 API also supports HTTP methods GET and DELETE where appropriate.
. Endpoint structure: The v2 API endpoint structure has been rationalized and
regularized.
-. Documentation: The v2 APIs are self-documenting: append `/_introspect` to
any valid v2 API path and the API specification will be returned in JSON format.
== v2 API Path Prefixes
@@ -49,101 +48,18 @@ Following are some v2 API URL paths and path prefixes,
along with some of the op
|`/api/cores` |Create a core.
|`/api/cores/\{coreName}` |Reload, rename, delete, and unload a core.
|`/api/node` |Perform overseer operation, rejoin leader election.
-|`/api/cluster` |List live nodes, manage node roles, set cluster property.
`POST` sets the cluster rate limiter.
+|`/api/cluster/nodes` |List live nodes.
+|`/api/cluster/properties` |List, get, set, and delete cluster properties.
+|`/api/cluster` |`POST` sets the cluster rate limiter.
|===
-== Introspect
-
-Append `/_introspect` to any valid v2 API path and the API specification will
be returned in JSON format.
-
-`\http://localhost:8983/api/c/_introspect`
-
-To limit the introspect output to include just one particular HTTP method, add
the request parameter `method` with value `GET`, `POST`, or `DELETE`.
-
-`\http://localhost:8983/api/c/_introspect?method=POST`
-
-Most endpoints support commands provided in a body sent via POST.
-To limit the introspect output to only one command, add the request parameter
`command=_command-name_`.
-
-`\http://localhost:8983/api/c/gettingstarted/_introspect?method=POST&command=modify`
-
-=== Interpreting the Introspect Output
-
-Example: `\http://localhost:8983/api/c/gettingstarted/get/_introspect`
-
-[source,json]
-----
-{
- "spec":[{
-
"documentation":"https://solr.apache.org/guide/solr/latest/configuration-guide/realtime-get.html";,
- "description":"RealTime Get allows retrieving documents by ID before the
documents have been committed to the index. It is useful when you need access
to documents as soon as they are indexed but your commit times are high for
other reasons.",
- "methods":["GET"],
- "url":{
- "paths":["/c/gettingstarted/get"],
- "params":{
- "id":{
- "type":"string",
- "description":"A single document ID to retrieve."},
- "ids":{
- "type":"string",
- "description":"One or more document IDs to retrieve. Separate by
commas if more than one ID is specified."},
- "fq":{
- "type":"string",
- "description":"An optional filter query to add to the query. One
use case for this is security filtering, in case users or groups should not be
able to retrieve the document ID requested."}}}}],
- "WARNING":"This response format is experimental. It is likely to change in
the future.",
- "availableSubPaths":{}
-}
-----
-
-Description of some of the keys in the above example:
-
-* `**documentation**`: URL to the online Solr reference guide section for this
API
-* `**description**`: A text description of the feature/variable/command, etc.
-* `**spec/methods**`: HTTP methods supported by this API
-* `**spec/url/paths**`: URL paths supported by this API
-* `**spec/url/params**`: List of supported URL request params
-* `**availableSubPaths**`: List of valid URL subpaths and the HTTP method(s)
each supports
-
-Example of introspect for a POST API:
`\http://localhost:8983/api/c/gettingstarted/_introspect?method=POST&command=modify`
-
-[source,json]
-----
-{
- "spec":[{
-
"documentation":"https://solr.apache.org/guide/solr/latest/configuration-guide/collections-api.html";,
- "description":"Several collection-level operations are supported with
this endpoint: modify collection attributes; reload a collection; migrate
documents to a different collection; rebalance collection leaders; balance
properties across shards; and add or delete a replica property.",
- "methods":["POST"],
- "url":{"paths":["/collections/{collection}",
- "/c/{collection}"]},
- "commands":{"modify":{
-
"documentation":"https://solr.apache.org/guide/solr/latest/deployment-guide/collection-management.html#modifycollection";,
- "description":"Modifies specific attributes of a collection.
Multiple attributes can be changed at one time.",
- "type":"object",
- "properties":{
- "replicationFactor":{
- "type":"string",
- "description":"The number of replicas to be created for each
shard. Replicas are physical copies of each shard, acting as failover for the
shard. Note that changing this value on an existing collection does not
automatically add more replicas to the collection. However, it will allow
add-replica commands to succeed."}}}}}],
- "WARNING":"This response format is experimental. It is likely to change in
the future.",
- "availableSubPaths":{
- "/c/gettingstarted/select":["POST", "GET"],
- "/c/gettingstarted/config":["POST", "GET"],
- "/c/gettingstarted/schema":["POST", "GET"],
- "/c/gettingstarted/export":["POST", "GET"],
- "/c/gettingstarted/admin/ping":["POST", "GET"],
- "/c/gettingstarted/update":["POST"]}
-}
-----
-
-The `"commands"` section in the above example has one entry for each command
supported at this endpoint.
-The key is the command name and the value is a JSON object describing the
command structure using JSON schema (see http://json-schema.org/ for a
description).
-
== Invocation Examples
-For the "gettingstarted" collection, set the replication factor and whether to
automatically add replicas (see above for the introspect output for the
`"modify"` command used here):
+For the "gettingstarted" collection, set the replication factor and whether to
automatically add replicas:
[source,bash]
----
-curl http://localhost:8983/api/c/gettingstarted -H
'Content-type:application/json' -d '
+curl 'http://localhost:8983/api/c/gettingstarted' -H
'Content-type:application/json' -d '
{ modify: { replicationFactor: "3" } }'
{"responseHeader":{"status":0,"QTime":842}}
@@ -153,7 +69,7 @@ See the collections, shards, and replicas in the cluster:
[source,bash]
----
-curl http://localhost:8983/api/collections?detailed=true
+curl 'http://localhost:8983/api/collections?detailed=true'
{"responseHeader":{"status":0,"QTime":1},"collectionsDetail":{"gettingstarted":{"health":"GREEN","shards":{"shard1":{"state":"active"}}}}}
----
@@ -162,8 +78,8 @@ Set a cluster property:
[source,bash]
----
-curl http://localhost:8983/api/cluster -H 'Content-type: application/json' -d '
-{ set-property: { name: maxCoresPerNode, val: "100" } }'
+curl -X PUT 'http://localhost:8983/api/cluster/properties/urlScheme' -H
'Content-type: application/json' -d '
+{ "value": "http" }'
{"responseHeader":{"status":0,"QTime":4}}
----
