Improve API docs by moving schema descriptions and fixing workspace r…

…eturn types (#301) * Move descriptions of parameters under 'schema' one level up, to be visible in api console and to comply with spec * Fix up return types of endpoints returning workspaces
gristlabs · Jan 12, 2024 · 8dd6835 · 8dd6835
1 parent 01c4e62
commit 8dd6835
Show file tree

Hide file tree

Showing 12 changed files with 665 additions and 679 deletions.
diff --git a/api/grist.yml b/api/grist.yml
@@ -101,11 +101,12 @@ paths:
       responses:
         200:
           description: Success
+
   /orgs/{orgId}/workspaces:
     get:
       operationId: listWorkspaces
       tags:
-        - orgs
+        - workspaces
       summary: "List workspaces and documents within an org"
       parameters:
         - $ref: '#/components/parameters/orgIdPathParam'
@@ -115,7 +116,9 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/OrgWithWorkspaces"
+                type: array
+                items:
+                  $ref: "#/components/schemas/WorkspaceWithDocsAndDomain"
     post:
       operationId: createWorkspace
       tags:
@@ -156,7 +159,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/WorkspaceWithOrg"
+                $ref: "#/components/schemas/WorkspaceWithDocsAndOrg"
     patch:
       operationId: modifyWorkspace
       tags:
@@ -1336,10 +1339,6 @@ components:
           type: string
           nullable: true
           example: null
-    Workspaces:
-      type: array
-      items:
-        $ref: "#/components/schemas/Workspace"
     WorkspaceWithDocs:
       allOf:
         - $ref: "#/components/schemas/Workspace"
@@ -1351,6 +1350,14 @@ components:
               type: array
               items:
                 $ref: "#/components/schemas/Doc"
+    WorkspaceWithDocsAndDomain:
+      allOf:
+        - $ref: "#/components/schemas/WorkspaceWithDocs"
+        - type: object
+          properties:
+            orgDomain:
+              type: string
+              example: "gristlabs"
     WorkspaceWithOrg:
       allOf:
         - $ref: "#/components/schemas/Workspace"
@@ -1360,17 +1367,10 @@ components:
           properties:
             org:
               $ref: "#/components/schemas/Org"
-    OrgWithWorkspaces:
+    WorkspaceWithDocsAndOrg:
       allOf:
-        - $ref: "#/components/schemas/Org"
-        - type: object
-          required:
-          - workspaces
-          properties:
-            workspaces:
-              type: array
-              items:
-                $ref: "#/components/schemas/WorkspaceWithDocs"
+        - $ref: "#/components/schemas/WorkspaceWithDocs"
+        - $ref: "#/components/schemas/WorkspaceWithOrg"
     DocWithWorkspace:
       allOf:
         - $ref: "#/components/schemas/Doc"
@@ -2014,54 +2014,54 @@ components:
       name: filter
       schema:
         type: string
-        description: "This is a JSON object mapping column names to arrays of allowed values.  For example, to filter column `pet` for values `cat` and `dog`, the filter would be `{\"pet\": [\"cat\", \"dog\"]}`. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them.  For this example, the url-encoding is `%7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D`. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for `pet` being either `cat` or `dog`, AND `size` being either `tiny` or `outrageously small`, would be `{\"pet\": [\"cat\", \"dog\"], \"size\": [\"tiny\", \"outrageously small\"]}`."
-        example: "{\"pet\": [\"cat\", \"dog\"]}"
+      description: "This is a JSON object mapping column names to arrays of allowed values.  For example, to filter column `pet` for values `cat` and `dog`, the filter would be `{\"pet\": [\"cat\", \"dog\"]}`. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them.  For this example, the url-encoding is `%7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D`. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for `pet` being either `cat` or `dog`, AND `size` being either `tiny` or `outrageously small`, would be `{\"pet\": [\"cat\", \"dog\"], \"size\": [\"tiny\", \"outrageously small\"]}`."
+      example: "{\"pet\": [\"cat\", \"dog\"]}"
       required: false
     sortQueryParam:
       in: query
       name: sort
       schema:
         type: string
-        description: "Order in which to return results. If a single column name is given (e.g. `pet`), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special `manualSort` column name. Multiple columns can be specified, separated by commas (e.g. `pet,age`). For descending order, prefix a column name with a `-` character (e.g. `pet,-age`). To include additional sorting options append them after a colon (e.g. `pet,-age:naturalSort;emptyFirst,owner`). Available options are: `choiceOrder`, `naturalSort`, `emptyFirst`. Without the `sort` parameter, the order of results is unspecified."
-        example: "pet,-age"
+      description: "Order in which to return results. If a single column name is given (e.g. `pet`), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special `manualSort` column name. Multiple columns can be specified, separated by commas (e.g. `pet,age`). For descending order, prefix a column name with a `-` character (e.g. `pet,-age`). To include additional sorting options append them after a colon (e.g. `pet,-age:naturalSort;emptyFirst,owner`). Available options are: `choiceOrder`, `naturalSort`, `emptyFirst`. Without the `sort` parameter, the order of results is unspecified."
+      example: "pet,-age"
       required: false
     limitQueryParam:
       in: query
       name: limit
       schema:
         type: number
-        description: "Return at most this number of rows.  A value of 0 is equivalent to having no limit."
-        example: "5"
+      description: "Return at most this number of rows.  A value of 0 is equivalent to having no limit."
+      example: "5"
       required: false
     sortHeaderParam:
       in: header
       name: X-Sort
       schema:
         type: string
-        description: "Same as `sort` query parameter."
-        example: "pet,-age"
+      description: "Same as `sort` query parameter."
+      example: "pet,-age"
       required: false
     limitHeaderParam:
       in: header
       name: X-Limit
       schema:
         type: number
-        description: "Same as `limit` query parameter."
-        example: "5"
+      description: "Same as `limit` query parameter."
+      example: "5"
       required: false
     colIdPathParam:
       in: path
       name: colId
       schema:
         type: string
-        description: The column id (without the starting `$`) as shown in the column configuration below the label
+      description: The column id (without the starting `$`) as shown in the column configuration below the label
       required: true
     tableIdPathParam:
       in: path
       name: tableId
       schema:
         type: string
-        description: normalized table name (see `TABLE ID` in Raw Data) or numeric row ID in `_grist_Tables`
+      description: normalized table name (see `TABLE ID` in Raw Data) or numeric row ID in `_grist_Tables`
       required: true
     docIdPathParam:
       in: path
@@ -2091,20 +2091,20 @@ components:
       name: noparse
       schema:
         type: boolean
-        description: "Set to true to prohibit parsing strings according to the column type."
+      description: "Set to true to prohibit parsing strings according to the column type."
     hiddenQueryParam:
       in: query
       name: hidden
       schema:
         type: boolean
-        description: "Set to true to include the hidden columns (like \"manualSort\")"
+      description: "Set to true to include the hidden columns (like \"manualSort\")"
     headerQueryParam:
       in: query
       name: header
       schema:
         type: string
-        description: "Format for headers. Labels tend to be more human-friendly while colIds are more normalized."
         enum:
           - colId
           - label
+      description: "Format for headers. Labels tend to be more human-friendly while colIds are more normalized."
       required: false
diff --git a/help/api.md b/help/api.md
diff --git a/help/code/enums/GristData.GristObjCode.md b/help/code/enums/GristData.GristObjCode.md
@@ -2,7 +2,7 @@
 
 [GristData](../modules/GristData.md).GristObjCode
 
-Letter codes for CellValue types encoded as [code, args...] tuples.
+Letter codes for [CellValue](../modules/GristData.md#cellvalue) types encoded as [code, args...] tuples.
 
 ## Table of contents
 

diff --git a/help/code/interfaces/GristData.RowRecord.md b/help/code/interfaces/GristData.RowRecord.md
@@ -2,29 +2,4 @@
 
 [GristData](../modules/GristData.md).RowRecord
 
-Map of column ids to `CellValue`s.
-
-### CellValue
-
-Each `CellValue` may either be a primitive (e.g. `true`, `123`, `"hello"`, `null`)
-or a tuple (JavaScript Array) representing a Grist object. The first element of the tuple
-is a string character representing the object code. For example, `["L", "foo", "bar"]`
-is a `CellValue` of a Choice List column, where `"L"` is the type, and `"foo"` and
-`"bar"` are the choices.
-
-### Grist Object Types
-
-| Code | Type           |
-| ---- | -------------- |
-| L    | List           |
-| l    | LookUp         |
-| O    | Dict           |
-| D    | DateTime       |
-| d    | Date           |
-| C    | Censored       |
-| R    | Reference      |
-| r    | ReferenceList  |
-| E    | Exception      |
-| P    | Pending        |
-| U    | Unmarshallable |
-| V    | Version        |
+Map of column ids to [CellValue](../modules/GristData.md#cellvalue)'s.
diff --git a/help/code/interfaces/GristData.RowRecords.md b/help/code/interfaces/GristData.RowRecords.md
@@ -2,30 +2,5 @@
 
 [GristData](../modules/GristData.md).RowRecords
 
-Map of column ids to `CellValue` arrays, where array indexes correspond to
+Map of column ids to [CellValue](../modules/GristData.md#cellvalue) arrays, where array indexes correspond to
 rows.
-
-### CellValue
-
-Each `CellValue` may either be a primitive (e.g. `true`, `123`, `"hello"`, `null`)
-or a tuple (JavaScript Array) representing a Grist object. The first element of the tuple
-is a string character representing the object code. For example, `["L", "foo", "bar"]`
-is a `CellValue` of a Choice List column, where `"L"` is the type, and `"foo"` and
-`"bar"` are the choices.
-
-### Grist Object Types
-
-| Code | Type           |
-| ---- | -------------- |
-| L    | List           |
-| l    | LookUp         |
-| O    | Dict           |
-| D    | DateTime       |
-| d    | Date           |
-| C    | Censored       |
-| R    | Reference      |
-| r    | ReferenceList  |
-| E    | Exception      |
-| P    | Pending        |
-| U    | Unmarshallable |
-| V    | Version        |
diff --git a/help/code/interfaces/TableOperations.UpsertOptions.md b/help/code/interfaces/TableOperations.UpsertOptions.md
@@ -40,7 +40,7 @@ ___
 
 ### onMany
 
-• `Optional` **onMany**: ``"none"`` \| ``"first"`` \| ``"all"``
+• `Optional` **onMany**: ``"all"`` \| ``"none"`` \| ``"first"``
 
 Whether to update none, one, or all matching records. Defaults to "first".
 

diff --git a/help/code/interfaces/grist_plugin_api.CursorPos.md b/help/code/interfaces/grist_plugin_api.CursorPos.md
@@ -9,6 +9,7 @@ Represents the position of an active cursor on a page.
 ### Properties
 
 - [fieldIndex](grist_plugin_api.CursorPos.md#fieldindex)
+- [linkingRowIds](grist_plugin_api.CursorPos.md#linkingrowids)
 - [rowId](grist_plugin_api.CursorPos.md#rowid)
 - [rowIndex](grist_plugin_api.CursorPos.md#rowindex)
 - [sectionId](grist_plugin_api.CursorPos.md#sectionid)
@@ -23,6 +24,15 @@ The index of the selected field in the current view.
 
 ___
 
+### linkingRowIds
+
+• `Optional` **linkingRowIds**: [`UIRowId`](../modules/grist_plugin_api.md#uirowid)[]
+
+When in a linked section, CursorPos may include which rows in the controlling sections are
+selected: the rowId in the linking-source section, in _that_ section's linking source, etc.
+
+___
+
 ### rowId
 
 • `Optional` **rowId**: [`UIRowId`](../modules/grist_plugin_api.md#uirowid)

diff --git a/help/code/interfaces/grist_plugin_api.FetchSelectedOptions.md b/help/code/interfaces/grist_plugin_api.FetchSelectedOptions.md
@@ -47,5 +47,5 @@ ___
 
 • `Optional` **keepEncoded**: `boolean`
 
-- `true`: the returned data will contain raw `CellValue`s.
+- `true`: the returned data will contain raw [CellValue](../modules/GristData.md#cellvalue)'s.
 - `false`: the values will be decoded, replacing e.g. `['D', timestamp]` with a moment date.
diff --git a/help/code/interfaces/grist_plugin_api.GristView.md b/help/code/interfaces/grist_plugin_api.GristView.md
@@ -52,7 +52,8 @@ ___
 
 ▸ **fetchSelectedTable**(`options?`): `Promise`<`any`\>
 
-Like [GristDocAPI.fetchTable](grist_plugin_api.GristDocAPI.md#fetchtable), but gets data for the custom section specifically, if there is any.
+Like [GristDocAPI.fetchTable](grist_plugin_api.GristDocAPI.md#fetchtable),
+but gets data for the custom section specifically, if there is any.
 By default, `options.keepEncoded` is `true` and `format` is `columns`.
 
 #### Parameters

diff --git a/help/code/modules/GristData.md b/help/code/modules/GristData.md
@@ -22,3 +22,26 @@
 Ƭ **CellValue**: `number` \| `string` \| `boolean` \| ``null`` \| [[`GristObjCode`](../enums/GristData.GristObjCode.md), ...unknown[]]
 
 Possible types of cell content.
+
+Each `CellValue` may either be a primitive (e.g. `true`, `123`, `"hello"`, `null`)
+or a tuple (JavaScript Array) representing a Grist object. The first element of the tuple
+is a string character representing the object code. For example, `["L", "foo", "bar"]`
+is a `CellValue` of a Choice List column, where `"L"` is the type, and `"foo"` and
+`"bar"` are the choices.
+
+### Grist Object Types
+
+| Code | Type           |
+| ---- | -------------- |
+| `L`  | List, e.g. `["L", "foo", "bar"]` or `["L", 1, 2]` |
+| `l`  | LookUp, as `["l", value, options]` |
+| `O`  | Dict, as `["O", {key: value, ...}]` |
+| `D`  | DateTimes, as `["D", timestamp, timezone]`, e.g. `["D", 1704945919, "UTC"]` |
+| `d`  | Date, as `["d", timestamp]`, e.g. `["d", 1704844800]` |
+| `C`  | Censored, as `["C"]` |
+| `R`  | Reference, as `["R", table_id, row_id]`, e.g. `["R", "People", 17]` |
+| `r`  | ReferenceList, as `["r", table_id, row_id_list]`, e.g. `["r", "People", [1,2]]` |
+| `E`  | Exception, as `["E", name, ...]`, e.g. `["E", "ValueError"]` |
+| `P`  | Pending, as `["P"]` |
+| `U`  | Unmarshallable, as `["U", text_representation]` |
+| `V`  | Version, as `["V", version_obj]` |
diff --git a/help/code/modules/grist_plugin_api.md b/help/code/modules/grist_plugin_api.md
@@ -158,7 +158,8 @@ ___
 
 ▸ **fetchSelectedRecord**(`rowId`, `options?`): `Promise`<`any`\>
 
-Same as [GristView.fetchSelectedRecord](../interfaces/grist_plugin_api.GristView.md#fetchselectedrecord), but the option `keepEncoded` is `false` by default.
+Same as [GristView.fetchSelectedRecord](../interfaces/grist_plugin_api.GristView.md#fetchselectedrecord),
+but the option `keepEncoded` is `false` by default.
 
 #### Parameters
 
@@ -177,7 +178,8 @@ ___
 
 ▸ **fetchSelectedTable**(`options?`): `Promise`<`any`\>
 
-Same as [GristView.fetchSelectedTable](../interfaces/grist_plugin_api.GristView.md#fetchselectedtable), but the option `keepEncoded` is `false` by default.
+Same as [GristView.fetchSelectedTable](../interfaces/grist_plugin_api.GristView.md#fetchselectedtable),
+but the option `keepEncoded` is `false` by default.
 
 #### Parameters
 

diff --git a/overrides/api-head.html b/overrides/api-head.html