This is an automated email from the ASF dual-hosted git repository. dsmiley pushed a commit to branch branch_10x in repository https://gitbox.apache.org/repos/asf/solr.git
commit 09647735fb6e3e7c137eb81feb81420409178558 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) (cherry picked from commit cf4a66669d37a308ac02bfd0211abe1897330df7) --- .../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}} ----
