From f5aaca6c816da365929ba63dd8eaac181353d03e Mon Sep 17 00:00:00 2001 From: Florent Date: Wed, 31 Jul 2024 18:47:59 +0200 Subject: [PATCH] documentation: user deletion API (#367) Co-authored-by: Vincent Viers <30295971+vviers@users.noreply.github.com> --- api/body.hbs | 6 ++++++ api/grist.yml | 44 +++++++++++++++++++++++++++++++++++++++++ help/en/docs/api.md | 25 +++++++++++++++++++---- overrides/api-head.html | 6 +++++- 4 files changed, 76 insertions(+), 5 deletions(-) diff --git a/api/body.hbs b/api/body.hbs index 16fe6e238..2e15e78fb 100644 --- a/api/body.hbs +++ b/api/body.hbs @@ -33,6 +33,12 @@ toc: - title: "/webhooks" url: "#tag/webhooks" + - + title: "/sql" + url: "#tag/sql" + - + title: "/users" + url: "#tag/users" - title: "Deprecated endpoints" url: "#tag/data" diff --git a/api/grist.yml b/api/grist.yml index 54f891958..d37d53c99 100644 --- a/api/grist.yml +++ b/api/grist.yml @@ -1104,6 +1104,39 @@ paths: application/json: schema: $ref: "#/components/schemas/SqlResultSet" + /users/{userId}: + delete: + tags: + - users + summary: "Delete a user from Grist" + description: | + This action also deletes the user's personal organisation and all the workspaces and documents it contains. + Currently, only the users themselves are allowed to delete their own accounts. + + ⚠️ **This action cannot be undone, please be cautious when using this endpoint** ⚠️ + parameters: + - $ref: '#/components/parameters/userIdPathParam' + requestBody: + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + type: string + description: "The user's name to delete (for confirmation, to avoid deleting the wrong account)." + example: "John Doe" + responses: + 200: + description: "The account has been deleted successfully" + 400: + description: "The passed user name does not match the one retrieved from the database given the passed user id" + 403: + description: "The caller is not allowed to delete this account" + 404: + description: "The user is not found" tags: - name: orgs @@ -1124,6 +1157,10 @@ tags: description: "Documents may include attached files. Data records can refer to these using a column of type `Attachments`." - name: webhooks description: "Document changes can trigger requests to URLs called webhooks." + - name: sql + description: "Sql endpoint to query data from documents." + - name: users + description: "Grist users." components: securitySchemes: ApiKey: @@ -2119,6 +2156,13 @@ components: schema: type: integer required: true + userIdPathParam: + in: path + name: userId + schema: + type: integer + description: A user id + required: true noparseQueryParam: in: query name: noparse diff --git a/help/en/docs/api.md b/help/en/docs/api.md index 6d12d2b53..a544cf5a2 100644 --- a/help/en/docs/api.md +++ b/help/en/docs/api.md @@ -33,6 +33,12 @@ toc: - title: "/webhooks" url: "#tag/webhooks" + - + title: "/sql" + url: "#tag/sql" + - + title: "/users" + url: "#tag/users" - title: "Deprecated endpoints" url: "#tag/data" @@ -51,7 +57,7 @@ REST API for manipulating documents, workspaces, and team sites.
-
API docs by Redocly
API docs by Redocly
webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Empty a document's queue of undelivered payloads

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

Responses

sql

Run an SQL query against a document

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

+

sql

Sql endpoint to query data from documents.

+

Run an SQL query against a document

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

query Parameters
q
string

The SQL query to run. This GET endpoint is a simplified version of the corresponding POST endpoint, without support for parameters or options. See the POST endpoint for details of what's allowed in the SQL query string.

Responses

Response samples

Content type
application/json
{
  • "statement": "select * from Pets ...",
  • "records": [
    • {
      • "fields": {
        • "id": 1,
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "fields": {
        • "id": 2,
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}

Run an SQL query against a document, with options or parameters

Authorizations:
ApiKey
path Parameters
docId
required
string

A string id (UUID)

@@ -275,9 +282,19 @@ Also note that some query parameters alter this behavior.

Array of numbers or strings

Parameters for the query.

timeout
number

Timeout after which operations on the document will be interrupted. Specified in milliseconds. Defaults to 1000 (1 second). This default is controlled by an optional environment variable read by the Grist app, GRIST_SQL_TIMEOUT_MSEC. The default cannot be exceeded, only reduced.

Responses

Request samples

Content type
application/json
{
  • "sql": "select * from Pets where popularity >= ?",
  • "args": [
    • 50
    ],
  • "timeout": 500
}

Response samples

Content type
application/json
{
  • "statement": "select * from Pets ...",
  • "records": [
    • {
      • "fields": {
        • "id": 1,
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "fields": {
        • "id": 2,
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}
+

Request samples

Content type
application/json
{
  • "sql": "select * from Pets where popularity >= ?",
  • "args": [
    • 50
    ],
  • "timeout": 500
}

Response samples

Content type
application/json
{
  • "statement": "select * from Pets ...",
  • "records": [
    • {
      • "fields": {
        • "id": 1,
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "fields": {
        • "id": 2,
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}

users

Users of Grist

+

Delete a user from Grist

Also delete the user's personal org (aka team site). +Currently only the user themselves is allowed to delete their own account.

+

⚠️ This cannot be undone, please be cautious when using this endpoint ⚠️

+
Authorizations:
ApiKey
path Parameters
userId
required
integer

A user id

+
Request Body schema: application/json
name
required
string

The user's name to delete (for confirmation, to avoid deleting the wrong account).

+

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe"
}