v2 API
The v2 API is a modernized self-documenting 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.
You can disable all v2 API endpoints if desired by starting your servers with this system property: -Ddisable.v2.api=true
.
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:
-
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
Following are some v2 API URL paths and path prefixes, along with some of the operations that are supported at these paths and their sub-paths.
Path prefix | Some Supported Operations |
---|---|
|
Create, alias, backup, and restore a collection. |
|
Update requests. |
|
Configuration requests. |
|
Schema requests. |
|
Handler-specific requests. |
|
Split a shard, create a shard, add a replica. |
|
Delete a shard, force leader election |
|
Delete a replica. |
|
Create a core. |
|
Reload, rename, delete, and unload a core. |
|
Perform overseer operation, rejoin leader election. |
|
Add role, remove role, set cluster property. |
|
Upload and download blobs and metadata. |
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
{
"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":{}
}
json
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
{
"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"]}
}
json
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):
$ curl http://localhost:8983/api/c/gettingstarted -H 'Content-type:application/json' -d '
{ modify: { replicationFactor: "3" } }'
{"responseHeader":{"status":0,"QTime":842}}
bash
See the state of the cluster:
$ curl http://localhost:8983/api/cluster
{"responseHeader":{"status":0,"QTime":0},"collections":["gettingstarted",".system"]}
bash
Set a cluster property:
$ curl http://localhost:8983/api/cluster -H 'Content-type: application/json' -d '
{ set-property: { name: maxCoresPerNode, val: "100" } }'
{"responseHeader":{"status":0,"QTime":4}}
bash