# REST API

```json metadata
{
  "title": "REST API",
  "description": "Documents the REST API available to Redis Software deployments.",
  "categories": ["docs","operate","rs"],
  "tableOfContents": {"sections":[{"children":[{"id":"permissions","title":"Permissions"},{"id":"certificates","title":"Certificates"}],"id":"authentication","title":"Authentication"},{"id":"ports","title":"Ports"},{"id":"versions","title":"Versions"},{"children":[{"id":"requests","title":"Requests"},{"id":"responses","title":"Responses"}],"id":"headers","title":"Headers"},{"id":"json-requests-and-responses","title":"JSON requests and responses"},{"id":"response-types-and-error-codes","title":"Response types and error codes"}]}

,
  "codeExamples": []
}
```Redis Software provides a REST API to help you automate common tasks.

Here, you'll find the details of the API and how to use it.  

For more info, see:

- Supported [request endpoints](https://redis.io/docs/latest/operate/rs/references/rest-api/requests), organized by path
- Supported [objects](https://redis.io/docs/latest/operate/rs/references/rest-api/objects), both request and response
- Built-in roles and associated [permissions](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions)
- [Redis Software REST API quick start](https://redis.io/docs/latest/operate/rs/references/rest-api/quick-start) with examples

## Authentication

Authentication to the Redis Software API occurs via [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Provide your username and password as the basic auth credentials.

If the username and password is incorrect or missing, the request will fail with a [`401 Unauthorized`](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) status code.

Example request using [cURL](https://curl.se/):

``` bash
curl -u "demo@redislabs.com:password" \
    https://localhost:9443/v1/bdbs
```

For more examples, see the [Redis Software REST API quick start](https://redis.io/docs/latest/operate/rs/references/rest-api/quick-start).

### Permissions

By default, the admin user is authorized for access to all endpoints. Use [role-based access controls](https://redis.io/docs/latest/operate/rs/security/access-control) and [role permissions](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions) to manage access.

If a user attempts to access an endpoint that is not allowed in their role, the request will fail with a [`403 Forbidden`](https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden) status code. For more details on which user roles can access certain endpoints, see [Permissions](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions).

### Certificates

The Redis Software REST API uses [Self-signed certificates](https://redis.io/docs/latest/operate/rs/security/certificates) to ensure the product is secure. When you use the default self-signed certificates, the HTTPS requests will fail with `SSL certificate problem: self signed certificate` unless you turn off SSL certificate verification.

## Ports

All calls must be made over SSL to port 9443. For the API to work, port 9443 must be exposed to incoming traffic or mapped to a different port.

If you are using a [Redis Software Docker image](https://redis.io/docs/latest/operate/rs/installing-upgrading/quickstarts/docker-quickstart), run the following command to start the Docker image with port 9443 exposed:

```sh
docker run -p 9443:9443 redislabs/redis
```

## Versions

All API requests are versioned in order to minimize the impact of backwards-incompatible API changes and to coordinate between different versions operating in parallel.

Specify the version in the request [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier), as shown in the following table:

| Request path | Description |
|--------------|-------------|
| POST `/v1/bdbs` | A version 1 request for the `/bdbs` endpoint. |
| POST `/v2/bdbs` | A version 2 request for the `/bdbs` endpoint. |

When an endpoint supports multiple versions, each version is documented on the corresponding endpoint.  For example, the [bdbs request](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs/) page documents POST requests for [version 1](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs/#post-bdbs-v1) and [version 2](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs/#post-bdbs-v2).

## Headers

### Requests

Redis Software REST API requests support the following HTTP headers:

| Header | Supported/Required Values |
|--------|---------------------------|
| Accept | `application/json` |
| Content-Length | Length (in bytes) of request message |
| Content-Type | `application/json` (required for PUT or POST requests) |

If the client specifies an invalid header, the request will fail with a [`400 Bad Request`](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) status code.

### Responses

Redis Software REST API responses support the following HTTP headers:

| Header | Supported/Required Values |
|--------|---------------------------|
| Content-Type | `application/json` |
| Content-Length | Length (in bytes) of response message |

## JSON requests and responses

The Redis Software REST API uses [JavaScript Object Notation (JSON)](http://www.json.org) for requests and responses. See the [RFC 4627 technical specifications](http://www.ietf.org/rfc/rfc4627.txt) for additional information about JSON.

Some responses may have an empty body but indicate the response with standard [HTTP codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).

Both requests and responses may include zero or more objects.

If the request is for a single entity, the response returns a single JSON object or none. If the request is for a list of entities, the response returns a JSON array with zero or more elements.

If you omit certain JSON object fields from a request, they may be assigned default values, which often indicate that these fields are not in use.

## Response types and error codes

[HTTP status codes](https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes) indicate the result of an API request. This can be `200 OK` if the server accepted the request, or it can be one of many error codes.

The most common responses for a Redis Software API request are:

| Response | Condition/Required handling |
|----------|-----------------------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | The request failed, generally due to a typo or other mistake. |
| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | The request failed because the authentication information was missing or incorrect. |
| [403 Forbidden](https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden) | The user cannot access the specified [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier). |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | The [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) does not exist. |
| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | The node is not responding or is not a member of the cluster. |
| [505 HTTP Version Not Supported](https://www.rfc-editor.org/rfc/rfc9110.html#name-505-http-version-not-suppor) | An unsupported `x-api-version` was used. See [versions](#versions). |

Some endpoints return different response codes. The request references for these endpoints document these special cases.