Stargate REST API reference

Abstract
The Stargate REST API provides CRUD operations on table data managed by Stargate.

1. Endpoints

1.1. Auth

1.1.1. createToken

POST /v1/auth

Create an auth token

Body Parameter
Name Description Required Default Pattern

Credentials

Credentials

X

Content Type
  • application/json

  • /

Responses
Table 1. http response codes
Code Message Datatype

201

Created

AuthTokenResponse

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error

1.2. Data

1.2.1. addRows

POST /v2/keyspaces/{keyspace-id}/{table-id}

Add rows

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

Body Parameter
Name Description Required Default Pattern

request_body

[string]

X

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Content Type
  • application/json

  • /

Responses
Table 2. http response codes
Code Message Datatype

201

resource created

Map[[string]]

400

Bad Request

Error

401

Unauthorized

Error

409

Conflict

Error

500

Internal server error

Error

1.2.2. deleteRows

DELETE /v2/keyspaces/{keyspace-id}/{table-id}/{primary-key}

delete a row(s)

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

primary-key

Value from the primary key column for the table. Define composite keys by separating values with slashes (`val1/val2…​`) in the order they were defined. </br> For example, if the composite key was defined as `PRIMARY KEY(race_year, race_name)` then the primary key in the path would be `race_year/race_name`

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Responses
Table 3. http response codes
Code Message Datatype

204

No Content

<<>>

401

Unauthorized

Error

500

Internal server error

Error

1.2.3. getRows

GET /v2/keyspaces/{keyspace-id}/{table-id}/{primary-key}

get a row(s)

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

primary-key

Value from the primary key column for the table. Define composite keys by separating values with slashes (`val1/val2…​`) in the order they were defined. </br> For example, if the composite key was defined as `PRIMARY KEY(race_year, race_name)` then the primary key in the path would be `race_year/race_name`

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

fields

URL escaped, comma delimited list of keys to include

-

null

page-size

restrict the number of returned items

-

null

page-state

move the cursor to a particular result

-

null

sort

keys to sort by [String]

-

null

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 4. http response codes
Code Message Datatype

200

[inline_response_200_3]

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error

1.2.4. replaceRows

PUT /v2/keyspaces/{keyspace-id}/{table-id}/{primary-key}

replace a row(s)

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

primary-key

Value from the primary key column for the table. Define composite keys by separating values with slashes (`val1/val2…​`) in the order they were defined. </br> For example, if the composite key was defined as `PRIMARY KEY(race_year, race_name)` then the primary key in the path would be `race_year/race_name`

X

null

Body Parameter
Name Description Required Default Pattern

request_body

document [string]

X

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 5. http response codes
Code Message Datatype

200

resource updated

[inline_response_200_4]

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error

1.2.5. searchTable

GET /v2/keyspaces/{keyspace-id}/{table-id}

search a table

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

where

URL escaped JSON query using the following keys:

Key

Operation

-

-

$lt

Less Than

$lte

Less Than Or Equal To

$gt

Greater Than

$gte

Greater Than Or Equal To

$ne

Not Equal To

$in

Contained In

$exists

A value is set for the key

-

null

fields

URL escaped, comma delimited list of keys to include

-

null

page-size

restrict the number of returned items

-

null

page-state

move the cursor to a particular result

-

null

sort

keys to sort by [String]

-

null

raw

unwrap results

-

Content Type
  • application/json

  • /

Responses
Table 6. http response codes
Code Message Datatype

200

[inline_response_200_3]

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error

1.2.6. updateRows

PATCH /v2/keyspaces/{keyspace-id}/{table-id}/{primary-key}

update part of a row(s)

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

primary-key

Value from the primary key column for the table. Define composite keys by separating values with slashes (`val1/val2…​`) in the order they were defined. </br> For example, if the composite key was defined as `PRIMARY KEY(race_year, race_name)` then the primary key in the path would be `race_year/race_name`

X

null

Body Parameter
Name Description Required Default Pattern

request_body

document [string]

X

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 7. http response codes
Code Message Datatype

200

resource updated

[inline_response_200_4]

400

Bad Request

Error

401

Unauthorized

Error

500

Internal server error

Error

1.3. Schemas

1.3.1. createColumn

POST /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns

create a column

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

Body Parameter
Name Description Required Default Pattern

ColumnDefinition

ColumnDefinition

X

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Content Type
  • application/json

  • /

Responses
Table 8. http response codes
Code Message Datatype

201

resource created

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

409

Conflict

Error

500

Internal server error

Error

1.3.2. createKeyspace

POST /v2/schemas/keyspaces

create a keyspace

Body Parameter
Name Description Required Default Pattern

Keyspace

Keyspace

X

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Content Type
  • application/json

  • /

Responses
Table 9. http response codes
Code Message Datatype

201

resource created

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

409

Conflict

Error

500

Internal server error

Error

1.3.3. createTable

POST /v2/schemas/keyspaces/{keyspace-id}/tables

create a table

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

Body Parameter
Name Description Required Default Pattern

TableAdd

TableAdd

X

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Content Type
  • application/json

  • /

Responses
Table 10. http response codes
Code Message Datatype

201

resource created

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

409

Conflict

Error

500

Internal server error

Error

1.3.4. deleteColumn

DELETE /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns/{column-id}

delete a column

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

column-id

column name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Responses
Table 11. http response codes
Code Message Datatype

204

No Content

<<>>

401

Unauthorized

Error

500

Internal server error

Error

1.3.5. deleteKeyspace

DELETE /v2/schemas/keyspaces/{keyspace-id}

delete a keyspace

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Responses
Table 12. http response codes
Code Message Datatype

204

No Content

<<>>

401

Unauthorized

Error

500

Internal server error

Error

1.3.6. deleteTable

DELETE /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}

delete a table

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Responses
Table 13. http response codes
Code Message Datatype

204

No Content

<<>>

401

Unauthorized

Error

500

Internal server error

Error

1.3.7. getColumn

GET /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns/{column-id}

get a column

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

column-id

column name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 14. http response codes
Code Message Datatype

200

ColumnDefinition

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error

1.3.8. getColumns

GET /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns

list columns

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 15. http response codes
Code Message Datatype

200

[inline_response_200_2]

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error

1.3.9. getKeyspace

GET /v2/schemas/keyspaces/{keyspace-id}

get a keyspace

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 16. http response codes
Code Message Datatype

200

Keyspace

400

Bad Request

Error

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error

1.3.10. getKeyspaces

GET /v2/schemas/keyspaces

Return all keyspaces

Description

Retrieve all available keyspaces in the specific database.

Parameters
Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 17. http response codes
Code Message Datatype

200

[inline_response_200]

401

Unauthorized

Error

500

Internal server error

Error

1.3.11. getTable

GET /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}

get a table

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 18. http response codes
Code Message Datatype

200

Table

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error

1.3.12. getTables

GET /v2/schemas/keyspaces/{keyspace-id}/tables

list tables

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Query Parameters
Name Description Required Default Pattern

raw

unwrap results

-

false

Content Type
  • application/json

  • /

Responses
Table 19. http response codes
Code Message Datatype

200

[inline_response_200_1]

401

Unauthorized

Error

404

Not Found

Error

500

Internal server error

Error

1.3.13. replaceColumn

PUT /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}/columns/{column-id}

replace a column definition

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

column-id

column name

X

null

Body Parameter
Name Description Required Default Pattern

ColumnDefinition

ColumnDefinition

X

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Content Type
  • application/json

  • /

Responses
Table 20. http response codes
Code Message Datatype

200

resource updated

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

404

Not Found

Error

409

Conflict

Error

500

Internal server error

Error

1.3.14. replaceTable

PUT /v2/schemas/keyspaces/{keyspace-id}/tables/{table-id}

replace a table definition, except for columns

Parameters
Path Parameters
Name Description Required Default Pattern

keyspace-id

keyspace name

X

null

table-id

table name

X

null

Body Parameter
Name Description Required Default Pattern

TableAdd

TableAdd

X

Header Parameters
Name Description Required Default Pattern

X-Cassandra-Token

The token returned from the authorization endpoint. Use this token in each request.

X

null

Content Type
  • application/json

  • /

Responses
Table 21. http response codes
Code Message Datatype

200

resource updated

[inline_response_201]

400

Bad Request

Error

401

Unauthorized

Error

404

Not Found

Error

409

Conflict

Error

500

Internal server error

Error

2. Models

2.1. AuthTokenResponse

Field Name Required Type Description Format

authToken

String

2.2. ClusteringExpression

Order rows storage to make use of the on-disk sorting of columns. Specifying order can make query results more efficient.

Field Name Required Type Description Format

column

X

String

order

X

String

Enum: ASC, DESC,

2.3. ColumnDefinition

Field Name Required Type Description Format

name

X

String

Name for the column, which must be unique.

typeDefinition

X

String

The type of data allowed in the column.

Enum: ascii, text, varchar, tinyint, smallint, int, bigint, varint, decimal, float, double, date, DateRangeType, duration, time, timestamp, uuid, timeuuid, blob, boolean, counter, inet, PointType, LineStringType, PolygonType, frozen, list, map, set, tuple,

static

Boolean

Denotes whether the column is shared by all rows of a partition.

2.4. Credentials

User credentials for authenticating

Field Name Required Type Description Format

username

X

String

Username

password

X

String

Password

2.5. Datacenter

Field Name Required Type Description Format

name

X

String

replicas

X

Integer

2.6. Error

A description of an error state

Field Name Required Type Description Format

description

String

A human readable description of the error state

code

Integer

The code referencing the error state

2.7. InlineResponse200

Field Name Required Type Description Format

data

List of Keyspace

2.8. InlineResponse2001

Field Name Required Type Description Format

data

List of Table

2.9. InlineResponse2002

Field Name Required Type Description Format

data

List of ColumnDefinition

2.10. InlineResponse2003

Field Name Required Type Description Format

data

List of [map]

count

Integer

2.11. InlineResponse2004

Field Name Required Type Description Format

data

Map of [string]

2.12. InlineResponse201

Field Name Required Type Description Format

name

String

2.13. Keyspace

Field Name Required Type Description Format

name

X

String

datacenters

List of Datacenter

2.14. PrimaryKey

Defines a column list for the primary key. Can be either a single column, compound primary key, or composite partition key. Provide multiple columns for the partition key to define a composite partition key.

Field Name Required Type Description Format

partitionKey

X

List of [string]

Name of the column or columns that constitute the partition key.

clusteringKey

List of [string]

Name of the column or columns that constitute the clustering key.

2.15. Table

Field Name Required Type Description Format

name

String

keyspace

String

columnDefinitions

List of ColumnDefinition

primaryKey

PrimaryKey

tableOptions

TableOptions

2.16. TableAdd

Field Name Required Type Description Format

name

X

String

ifNotExists

Boolean

Determines whether to create a new table if a table with the same name exists. Attempting to create an existing table returns an error unless this option is true.

columnDefinitions

X

List of ColumnDefinition

primaryKey

X

PrimaryKey

tableOptions

TableOptions

2.17. TableOptions

Field Name Required Type Description Format

defaultTimeToLive

Integer

Defines the Time To Live (TTL), which determines the time period (in seconds) to expire data. If the value is >0, TTL is enabled for the entire table and an expiration timestamp is added to each column. The maximum value is 630720000 (20 years). A new TTL timestamp is calculated each time the data is updated and the row is removed after the data expires.

clusteringExpression

List of ClusteringExpression