REST (JSON) API

REST (JSON) API REST (JSON) API enables Cube to deliver data over the HTTP protocol to certain kinds of data applications, including but not limited to the following ones:

Most commonly, front-end applications
Some data notebooks, e.g., Observable
Low-code tools, e.g., Retool
Automated jobs

Often, the REST (JSON) API is used to enable embedded analytics and real-time analytics use cases. See REST (JSON) API reference for the list of supported API endpoints. Also, check query format for details about query syntax.

You can find a mostly complete OpenAPI documentation for the REST (JSON) API in the linked openspec.yml file that you can use with tools like Swagger.

If you’ve chosen GraphQL as a query language for your front-end application, consider using the GraphQL API that Cube also provides.

REST (JSON) API also provides endpoints for GraphQL API and Orchestration API. However, they target specific use cases and are not considered part of the REST (JSON) API.

Transport

The REST (JSON) API supports the following transports:

Transport	Description	When to use
HTTP	HTTP-based protocol with long polling	Use by default
WebSocket	WebSocket-based protocol with support for real-time updates	Use for applications that require subscriptions to real-time updates

HTTP transport

You can use the curl utility to execute requests to the REST (JSON) API. Provide the API token in the Authorization header:

curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query={
    "dimensions": [
      "users.state",
      "users.city",
      "orders.status"
    ],
    "measures": [
      "orders.count"
    ],
    "filters": [
      {
        "member": "users.state",
        "operator": "notEquals",
        "values": ["us-wa"]
      }
    ],
    "timeDimensions": [
      {
        "dimension": "orders.created_at",
        "dateRange": ["2020-01-01", "2021-01-01"]
      }
    ],
    "limit": 10
  }' \
  http://localhost:4000/cubejs-api/v1/load

You can also use the jq utility to format responses from the REST (JSON) API in your terminal:

curl \
  -H "Authorization: TOKEN" \
  -G \
  --data-urlencode 'query={"measures": ["orders.count"]}' \
  http://localhost:4000/cubejs-api/v1/load | jq .data

You can also introspect the data model by querying the /v1/meta endpoint:

curl \
  -H "Authorization: TOKEN" \
  http://localhost:4000/cubejs-api/v1/meta | jq

You can also use the JavaScript SDK to call the REST (JSON) API from your JavaScript applications.

WebSocket transport

WebSocket transport can be used to provide real-time experience. You can configure it via the CUBEJS_WEB_SOCKETS environment variable. You can use the websocat utility to test the WebSocket transport:

websocat ws://localhost:4000/cubejs-api/v1/ws --text

After connecting, send the API token as the first message:

{"authorization":"TOKEN"}

Then, send requests. Each request should include a distinct messageId, the desired API endpoint in method, and additional params:

{"messageId":"1","method":"load","params":{"query":{"measures":["orders.count"]}}}

Clients using the JavaScript SDK can be switched to WebSocket by passing WebSocketTransport to the CubeApi constructor:

import cube from "@cubejs-client/core"
import WebSocketTransport from "@cubejs-client/ws-transport"

const cubeApi = cube({
  transport: new WebSocketTransport({
    authorization: TOKEN,
    apiUrl: "ws://localhost:4000/"
  })
})

See this recipe for an example of real-time data fetch using the WebSocket transport.

Configuration

REST (JSON) API is enabled by default and secured using API scopes and CORS. To find your REST (JSON) API endpoint in Cube Cloud, go to the Overview page, click API credentials, and choose the REST (JSON) API tab.

Base path

By default, all REST (JSON) API endpoints are prefixed with a base path of /cubejs-api, e.g., the /v1/load endpoint will be available at /cubejs-api/v1/load.

Exception: /livez and /readyz endpoints are not prefixed with a base path.

You can set a desired base path using the basePath configuration option.

API scopes

Each REST (JSON) API endpoint belongs to an API scope, e.g., the /v1/load endpoint belongs to the data scope. API scopes allow to secure access to API endpoints by making them accessible to specific users only or disallowing access for everyone. By default, API endpoints in all scopes, except for jobs, are accessible for everyone.

API scope	REST (JSON) API endpoints	Accessible by default?
`meta`	`/v1/meta`, Metadata API	✅ Yes
`data`	`/v1/load`, `/v1/cubesql`	✅ Yes
`graphql`	`/graphql`	✅ Yes
`sql`	`/v1/sql`	✅ Yes
`jobs`	`/v1/pre-aggregations/jobs`	❌ No
No scope	`/livez`, `/readyz`	✅ Yes

You can set accessible API scopes for all requests using the CUBEJS_DEFAULT_API_SCOPES environment variable. For example, to disallow access to the GraphQL API for everyone, set CUBEJS_DEFAULT_API_SCOPES to meta,data. You can also select accessible API scopes for each request using the contextToApiScopes configuration option, based on the provided security context. For example, to restrict access to the /v1/meta endpoint to service accounts only, you can set CUBEJS_DEFAULT_API_SCOPES to data,graphql and use the following configuration in the cube.js file, assuming that service accounts have service: true in their security context:

module.exports = {
  contextToApiScopes: (securityContext, defaultScopes) => {
    if (securityContext.service) {
      return ["meta", ...defaultScopes]
    }

    return defaultScopes
  }
}

CORS

REST (JSON) API supports Cross-Origin Resource Sharing (CORS). By default, requests from any origin (*) are allowed. You can configure CORS using the http.cors configuration option. For example, to allow requests from a specific domain only, use the following configuration in the cube.js file:

module.exports = {
  http: {
    cors: {
      origin: "https://example.com"
    }
  }
}

Prerequisites

Authentication

Cube uses API tokens to authorize requests and also for passing additional security context, which can be used in the queryRewrite property in your cube.js configuration file. The API Token is passed via the Authorization Header. The token itself is a JSON Web Token, the Security section describes how to generate it. In the development environment the token is not required for authorization, but you can still use it to pass a security context.

Error handling

Cube REST (JSON) API has basic errors and HTTP Error codes for all requests.

Status	Error response	Description
400	Error message	General error. It may be a database error, timeout, or other issue. Check error message for details.
403	Authorization header isn’t set	You didn’t provide an auth token. Provide a valid API Token or disable authorization.
403	Invalid token	The auth token provided is not valid. It may be expired or have invalid signature.
500	Error message	Cube internal server error. Check error message for details.

Request span annotation

For monitoring tools such as Cube Cloud proper request span annotation should be provided in x-request-id header of a request. Each request id should consist of two parts: spanId and requestSequenceId which define x-request-id as whole: ${spanId}-span-${requestSequenceId}. Values of x-request-id header should be unique for each separate request. spanId should define user interaction span such us Continue wait retry cycle and it’s value shouldn’t change during one single interaction.

Cache control

/v1/load and /v1/cubesql endpoints of the REST (JSON) API allow to control the in-memory cache behavior. The following querying strategies with regards to the cache are supported:

Strategy	Description
`stale-if-slow`	If refresh keys are up-to-date, returns cached value. If expired, tries to return fresh value from the data source. If the data source query is slow (hits `Continue wait`), returns stale value from cache.
`stale-while-revalidate`	If refresh keys are up-to-date, returns cached value. If expired, returns stale data from cache and updates cache in background.
`must-revalidate`	If refresh keys are up-to-date, returns cached value. If expired, always waits for fresh value from the data source, even if slow (hits one or more `Continue wait` intervals).
`no-cache`	Skips refresh key checks. Always returns fresh data from the data source, regardless of cache or query performance.

`Continue wait`

If the request takes too long to be processed, the REST (JSON) API responds with { "error": "Continue wait" } and the status code 200. This is part of the long polling mechanism:

After an API instance receives a request, it adds the query to the query queue.
If the query takes too long to be processed, the API instance will respond with Continue wait. Receiving Continue wait doesn’t mean the database query has been canceled, and it’s actually still being processed by Cube.
Clients who received Continue wait should continuously retry the same query in a loop until they get a successful result. Database queries that are no longer retried by clients will be marked as orphaned and removed from the query queue. Subsequent calls to the REST (JSON) API are idempotent and don’t lead to scheduling new database queries if not required by the refresh_key.

Possible reasons of Continue wait:

The query is too heavy for the upstream database, i.e., it takes too long to be processed.
The maximum concurrency is reached, i.e., there are many queries waiting in the query queue until the previous ones are completed.

continueWaitTimeout configuration option can be adjusted in order to change the time Cube waits before returning Continue wait message. However, it’s recommended to address the root cause of the issue instead of increasing the timeout:

Switch from a traditional database to a data warehouse.
Increase the concurrency if your database can handle it.
Implement pre-aggregations to reduce the query time by using Cube Store.

Data Modeling

Configuration

Core Data APIs

Embed APIs

Other APIs

JavaScript SDK

Transport

HTTP transport

WebSocket transport

Configuration

Base path

API scopes

CORS

Prerequisites

Authentication

Error handling

Request span annotation

Cache control

`Continue wait`

​Transport

​HTTP transport

​WebSocket transport

​Configuration

​Base path

​API scopes

​CORS

​Prerequisites

​Authentication

​Error handling

​Request span annotation

​Cache control

​Continue wait

Transport

HTTP transport

WebSocket transport

Configuration

Base path

API scopes

CORS

Prerequisites

Authentication

Error handling

Request span annotation

Cache control

`Continue wait`