DB Software v7.8

Accessing the HTTP API

SingleStore’s HTTP APIs can be accessed using Basic Authentication at protocol://hostname:port/api/version/ where:

  • protocol is HTTPS/HTTP; protocol must be HTTPS when SSL is enabled

  • hostname represents the host where SingleStore DB is running

  • port is the secure WebSocket proxy port configured

  • version is the HTTP API version; currently v1 and v2 are supported

To access SingleStore’s HTTP API via Basic Authentication, you need to provide your SingleStore account credentials (username and password) in each HTTP request. The credentials must be passed as a Base-64 encoded username:password string in the Authorization header in the HTTP client. For example, the Authorization header of demo:Afu4XjzB1ns would appear as follows.

Authorization: Basic ZGVtbzpBZnU0WGp6QjFucw==

Using an HTTP client such as cURL, you can either pass your credentials as parameters in the --user or the -u option or add them before the hostname in the HTTP request, as shown below.

curl -u "username:password" https://@hostname:port/api/v2/exec
curl https://username:password@hosname:port/api/v2/exec

cURL will then encode the username:password string using Base-64 and insert it in an Authorization header before sending the HTTP request to the server.

SingleStore currently supports the following API endpoints.

API Endpoint URL

Description

/api/v2/exec

Executes a SQL statement without returning result sets; typically used for executing DDL and DML statements for which result sets are not expected, such as CREATE TABLE and INSERT statements.

/ping

Verifies that the HTTP service is running and connectable.

/api/v2/query/rows

Executes a SQL statement and returns result sets; typically used for the SELECT statement for which result sets are expected. The result sets contain column names mapped to row values in a single field.

/api/v2/query/tuples

Executes a SQL statement and returns result sets along with the schema; typically used for the SELECT statement for which result sets are expected. The result sets contain rows and columns in separate fields with the schema displayed for each column.

/api/v2/spec

Returns the OpenAPI 3.0 specification for this service.

Note

The difference between /query/rows and /query/tuples endpoints lies in how the query results are presented in the JSON format. In addition, the /query/tuples endpoint offers better performance for queries with large result sets.

The HTTP request to the /ping endpoint does not require the SingleStore account credentials passed in an Authorization header.

You can use API development tools and libraries to send HTTP API requests and handle responses. You can also test-run the HTTP APIs at the Linux command line. For more information on how to use the HTTP APIs, refer to HTTP API Endpoints.

In this section: