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:

  1. 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.

  2. Endpoint structure: The v2 API endpoint structure has been rationalized and regularized.

  3. 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

/api/collections

Create, alias, backup, and restore a collection.

/api/c/collection-name/update

Update requests.

/api/c/collection-name/config

Configuration requests.

/api/c/collection-name/schema

Schema requests.

/api/c/collection-name/handler-name

Handler-specific requests.

/api/c/collection-name/shards

Split a shard, create a shard, add a replica.

/api/c/collection-name/shards/shard-name

Delete a shard, force leader election

/api/c/collection-name/shards/shard-name/replica-name

Delete a replica.

/api/cores

Create a core.

/api/cores/core-name

Reload, rename, delete, and unload a core.

/api/node

Perform overseer operation, rejoin leader election.

/api/cluster

Add role, remove role, set cluster property.

/api/c/.system/blob

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":{}
}

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"]}
}

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}}

See the state of the cluster:

$ curl http://localhost:8983/api/cluster

{"responseHeader":{"status":0,"QTime":0},"collections":["gettingstarted",".system"]}

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}}