From 7405fcd6a84257c741b6ae06aa3d4af0d8014949 Mon Sep 17 00:00:00 2001 From: John Smart Date: Wed, 12 Jul 2023 10:47:03 -0600 Subject: [PATCH] Inc review comments from Kathir --- .gitignore | 1 + api/StargateDocv2.yaml | 2 +- .../stargate-core/modules/ROOT/pages/FAQ.adoc | 7 +-- .../modules/develop/attachments/docv2.html | 48 +++++++++---------- 4 files changed, 30 insertions(+), 28 deletions(-) diff --git a/.gitignore b/.gitignore index 7f0085c2..c33b45a8 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ build .DS_store *~ package-lock.json +docs-src/.DS_Store # Logs logs diff --git a/api/StargateDocv2.yaml b/api/StargateDocv2.yaml index 27853ce5..fc29cc1b 100644 --- a/api/StargateDocv2.yaml +++ b/api/StargateDocv2.yaml @@ -9,7 +9,7 @@ info: url: https://www.datastax.com/contact-us version: 2.0.13 servers: -- url: /api/docs +- url: /api/rest tags: - name: Documents description: Document related operations. diff --git a/docs-src/stargate-core/modules/ROOT/pages/FAQ.adoc b/docs-src/stargate-core/modules/ROOT/pages/FAQ.adoc index db8c30c7..984fa4ca 100644 --- a/docs-src/stargate-core/modules/ROOT/pages/FAQ.adoc +++ b/docs-src/stargate-core/modules/ROOT/pages/FAQ.adoc @@ -4,11 +4,12 @@ == What should I do if I find a bug? -- If you've found an issue while using Stargate, please file a bug in the -https://github.com/stargate/stargate[Stargate repo] and use the bug label. +* If you've found an issue while using Stargate, please file a bug in the +https://github.com/stargate/stargate[Stargate repo, window="_blank"] and use the bug label. It's also helpful to include the full stack trace and the Stargate and database version that you are using so that we can efficiently debug. -- If you've found an issue with the documentation, please file an issue in the + +* If you've found an issue with the documentation, please file an issue in the https://github.com/stargate/docs[Stargate docs repo, window="_blank"]. Pull requests are also accepted! diff --git a/docs-src/stargate-develop/modules/develop/attachments/docv2.html b/docs-src/stargate-develop/modules/develop/attachments/docv2.html index e8a8f5e1..39a1d662 100644 --- a/docs-src/stargate-develop/modules/develop/attachments/docv2.html +++ b/docs-src/stargate-develop/modules/develop/attachments/docv2.html @@ -2258,7 +2258,7 @@

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "pageState": "c29tZS1leGFtcGxlLXN0YXRl"
}

Create a document

Create a new document with the generated ID. If the collection does not exist, it will be created.

+

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "pageState": "c29tZS1leGFtcGxlLXN0YXRl"
}

Create a document

Create a new document with the generated ID. If the collection does not exist, it will be created.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

query Parameters
ttl
integer <int32>

The time-to-live (in seconds) of the document.

@@ -2270,7 +2270,7 @@

Request samples

Content type
application/json
{
  • "location": "London",
  • "race": {
    }
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Create documents

Create multiple new documents. If the collection does not exist, it will be created.

+

Request samples

Content type
application/json
{
  • "location": "London",
  • "race": {
    }
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Create documents

Create multiple new documents. If the collection does not exist, it will be created.

Include the id-path parameter to extract the ID for each document from the document itself. The id-path should be given as path to the document property containing the id, for example a.b.c.[0]. @@ -2288,7 +2288,7 @@

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "documentIds": [
    ]
}

Get a document

Retrieve the JSON representation of a single document.

+

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "documentIds": [
    ]
}

Get a document

Retrieve the JSON representation of a single document.

Note that in case when conditions are given using the where query parameter or the page-size query parameter is defined, the response will contain an array of sub-documents where the condition is matched. The structure of returned sub-documents will only contain the path to the field which was included in the condition. @@ -2317,7 +2317,7 @@

Response samples

Content type
application/json
Example
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d",
  • "data": {
    }
}

Create or update a document

Create or update a document with a given ID. If the collection does not exist, it will be created. If the document already exists, it will be overwritten.

+

Response samples

Content type
application/json
Example
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d",
  • "data": {
    }
}

Create or update a document

Create or update a document with a given ID. If the collection does not exist, it will be created. If the document already exists, it will be overwritten.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

@@ -2330,7 +2330,7 @@

Request samples

Content type
application/json
{
  • "location": "London",
  • "race": {
    }
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Delete a document

Delete a document with a given ID.

+

Request samples

Content type
application/json
{
  • "location": "London",
  • "race": {
    }
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Delete a document

Delete a document with a given ID.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

@@ -2341,7 +2341,7 @@

Response samples

Content type
application/json
{
  • "code": 400,
  • "description": "Request invalid: payload not provided."
}

Patch a document

Patch a document with a given ID. Merges data at the root with requested data. Note that operation is not allowed if a JSON schema exist for a target collection.

+

Response samples

Content type
application/json
{
  • "code": 400,
  • "description": "Request invalid: payload not provided."
}

Patch a document

Patch a document with a given ID. Merges data at the root with requested data. Note that operation is not allowed if a JSON schema exist for a target collection.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

@@ -2354,7 +2354,7 @@

Request samples

Content type
application/json
{
  • "location": "Berlin"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Executes a a built-in function

Execute a built-in function (e.g. $push and $pop) against the root of this document. Performance may vary.

+

Request samples

Content type
application/json
{
  • "location": "Berlin"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Executes a a built-in function

Execute a built-in function (e.g. $push and $pop) against the root of this document. Performance may vary.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

@@ -2369,7 +2369,7 @@

Request samples

Content type
application/json
Example
{
  • "operation": "$pop"
}

Response samples

Content type
application/json

Note that data property content depends on the executed function:

+

Request samples

Content type
application/json
Example
{
  • "operation": "$pop"
}

Response samples

Content type
application/json

Note that data property content depends on the executed function:

  • $pop - returns the item that was popped from the array
  • $push - returns the complete array, including the item that was pushed
    • @@ -2404,7 +2404,7 @@

Response samples

Content type
application/json
Example

Response example when using a sub-document path /race on a document like:

+

Response samples

Content type
application/json
Example

Response example when using a sub-document path /race on a document like:

{ "location": "London", "race": { "competitors": 100, "start_date": "2022-08-15" } }

{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d",
  • "data": {
    }
}

Create or update a path in a document

Create or update a path in a document by ID. If the collection does not exist, it will be created. If data exists at the path, it will be overwritten.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

@@ -2420,7 +2420,7 @@

Request samples

Content type
application/json
{
  • "competitors": 100,
  • "start_date": "2022-08-15"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Delete a path in a document

Delete the data at a path in a document by ID.

+

Request samples

Content type
application/json
{
  • "competitors": 100,
  • "start_date": "2022-08-15"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Delete a path in a document

Delete the data at a path in a document by ID.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

@@ -2432,7 +2432,7 @@

Response samples

Content type
application/json
{
  • "code": 400,
  • "description": "Request invalid: payload not provided."
}

Patch a path in a document

Patch data at a path in a document by ID. Merges data at the path with requested data, assumes that the data at the path is already an object. Note that operation is not allowed if a JSON schema exist for a target collection.

+

Response samples

Content type
application/json
{
  • "code": 400,
  • "description": "Request invalid: payload not provided."
}

Patch a path in a document

Patch data at a path in a document by ID. Merges data at the path with requested data, assumes that the data at the path is already an object. Note that operation is not allowed if a JSON schema exist for a target collection.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

@@ -2446,7 +2446,7 @@

Request samples

Content type
application/json
{
  • "location": "Berlin"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Executes a a built-in function against a path in a document

Execute a built-in function (e.g. $push and $pop) against a value in this document. Performance may vary.

+

Request samples

Content type
application/json
{
  • "location": "Berlin"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Executes a a built-in function against a path in a document

Execute a built-in function (e.g. $push and $pop) against a value in this document. Performance may vary.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

@@ -2462,7 +2462,7 @@

Request samples

Content type
application/json
Example
{
  • "operation": "$pop"
}

Response samples

Content type
application/json

Note that data property content depends on the executed function:

+

Request samples

Content type
application/json
Example
{
  • "operation": "$pop"
}

Response samples

Content type
application/json

Note that data property content depends on the executed function:

  • $pop - returns the item that was popped from the array
  • $push - returns the complete array, including the item that was pushed
    • @@ -2476,7 +2476,7 @@

Response samples

Content type
application/json
{
  • "schema": [ ]
}

Attach a JSON schema

Assign a JSON schema to a collection. This will erase any schema that already exists.

+

Response samples

Content type
application/json
{
  • "schema": [ ]
}

Attach a JSON schema

Assign a JSON schema to a collection. This will erase any schema that already exists.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

Request Body schema: application/json

The JSON schema to attach

@@ -2486,7 +2486,7 @@

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "schema": [ ]
}

Collections

Collection management operations.

+

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "schema": [ ]
}

Collections

Collection management operations.

List collections

List all available collections in a namespace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

query Parameters
raw
boolean

Unwrap results.

@@ -2496,7 +2496,7 @@

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a collection

Create a new empty collection in a namespace.

+

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a collection

Create a new empty collection in a namespace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

Request Body schema: application/json
name
required
string\w+

The name of the collection.

Responses

Request samples

Content type
application/json
{
  • "name": "events"
}

Response samples

Content type
application/json
Example
{
  • "code": 400,
  • "description": "Could not create collection events-collection, it has invalid characters. Valid characters are alphanumeric and underscores."
}

Delete a collection

Delete a collection in a namespace.

+

Request samples

Content type
application/json
{
  • "name": "events"
}

Response samples

Content type
application/json
Example
{
  • "code": 400,
  • "description": "Could not create collection events-collection, it has invalid characters. Valid characters are alphanumeric and underscores."
}

Delete a collection

Delete a collection in a namespace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

Responses

Response samples

Content type
application/json
Example
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}

Upgrade a collection

Upgrade a collection in a namespace.

+

Response samples

Content type
application/json
Example
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}

Upgrade a collection

Upgrade a collection in a namespace.

WARNING: This endpoint is expected to cause some down-time for the collection you choose.

@@ -2528,14 +2528,14 @@

Request samples

Content type
application/json
{
  • "upgradeType": "SAI_INDEX_UPGRADE"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Namespaces

Namespace management operations.

+

Request samples

Content type
application/json
{
  • "upgradeType": "SAI_INDEX_UPGRADE"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Namespaces

Namespace management operations.

List namespaces

List all available namespaces. Note that a namespace is an equivalent to the Cassandra keyspace.

Authorizations:
Token
query Parameters
raw
boolean

Unwrap results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a namespace

Create a new namespace using given replication strategy. Note that a namespace is an equivalent to the Cassandra keyspace.

+

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a namespace

Create a new namespace using given replication strategy. Note that a namespace is an equivalent to the Cassandra keyspace.

Authorizations:
Token
Request Body schema: application/json

Request body

name
required
string\w+

The name of the namespace.

replicas
integer or null <int32> >= 1
Default: 1

The amount of replicas to use with the SimpleStrategy. Ignored if datacenters is set.

@@ -2546,7 +2546,7 @@

Request samples

Content type
application/json
Example
{
  • "name": "cycling",
  • "replicas": 1
}

Response samples

Content type
application/json
{
  • "name": "cycling",
  • "replicas": 1,
  • "datacenters": [
    ]
}

Get a namespace

Retrieve a single namespace specification. Note that a namespace is an equivalent to the Cassandra keyspace.

+

Request samples

Content type
application/json
Example
{
  • "name": "cycling",
  • "replicas": 1
}

Response samples

Content type
application/json
{
  • "name": "cycling",
  • "replicas": 1,
  • "datacenters": [
    ]
}

Get a namespace

Retrieve a single namespace specification. Note that a namespace is an equivalent to the Cassandra keyspace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

query Parameters
raw
boolean

Unwrap results.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a namespace

Delete a namespace if exists. Note that a namespace is an equivalent to the Cassandra keyspace.

+

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a namespace

Delete a namespace if exists. Note that a namespace is an equivalent to the Cassandra keyspace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

Responses

Response samples

Content type
application/json
Example
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}
+

Response samples

Content type
application/json
Example
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}