Update documentation.

ubccr · May 22, 2024 · 4daf0c2 · 4daf0c2
1 parent c630a2d
commit 4daf0c2
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 53 deletions.
diff --git a/classes/Rest/Controllers/WarehouseControllerProvider.php b/classes/Rest/Controllers/WarehouseControllerProvider.php
@@ -2108,16 +2108,16 @@ private function getUserStore(\XDUser $user, $realm)
      *
      * It can also contain the following optional parameters:
      * - fields: list of aliases of fields to get (if not provided, all
-     *           fields are gotten).
+     *           fields are obtained).
      * - filters: mapping of dimension names to their possible values.
      *            Results will only be included whose values for each of the
      *            given dimensions match one of the corresponding given values.
      * - offset: starting row index of data to get.
      *
-     * If successful, the response will include the following keys:
-     * - success: true.
-     * - fields: array containing the 'display' property of each field gotten.
-     * - data: array of arrays containing the field values gotten.
+     * If successful, the response will be a JSON text sequence. The first line
+     * will be an array containing the 'display' property of each obtained
+     * field. Subsequent lines will be arrays containing the obtained field
+     * values for each record.
      *
      * @param Request $request
      * @param Application $app

diff --git a/docs/xdmod-rest-schema.json b/docs/xdmod-rest-schema.json
@@ -1933,7 +1933,7 @@ layout: null
 
                         }
                     },
-                    "404": { "$ref": "api-token-404" }
+                    "404": { "$ref": "#/components/responses/api-token-404" }
                 }
             },
             "post": {
@@ -2111,7 +2111,7 @@ layout: null
                             }
                         }
                     },
-                    "404": { "$ref": "api-token-404" },
+                    "404": { "$ref": "#/components/responses/api-token-404" },
                     "500": {
                         "description": "Internal Server Error",
                         "content": {
@@ -2857,7 +2857,7 @@ layout: null
                     "Data Analytics Framework"
                 ],
                 "summary": "Get raw data from the data warehouse",
-                "description": "",
+                "description": "On success, returns a stream of content type `application/json-seq` containing one line with an array containing the `display` property of each obtained field followed by one line for each obtained record with an array containing the obtained field values for that record. Each line starts with an ASCII Record Separator character and ends with an ASCII Line Feed character.",
                 "operationId": "get-warehouse-raw-data",
                 "security": [
                     { "http_bearer": [] },
@@ -2916,51 +2916,7 @@ layout: null
                     "200": {
                         "description": "OK",
                         "content": {
-                            "application/json": {
-                                "schema": {
-                                    "type": "object",
-                                    "title": "success",
-                                    "properties": {
-                                        "success":  {
-                                            "type": "boolean",
-                                            "enum": [ true ]
-                                        },
-                                        "fields": {
-                                            "type": "array",
-                                            "description": "Labels of fields returned",
-                                            "items": {
-                                                "type": "string"
-                                            }
-                                        },
-                                        "data": {
-                                            "type": "array",
-                                            "description": "Rows of raw data",
-                                            "items": {
-                                                "type": "array",
-                                                "items": {
-                                                    "type": "string",
-                                                    "nullable": true
-                                                }
-                                            }
-                                        }
-                                    },
-                                    "required": [
-                                        "success",
-                                        "fields",
-                                        "data"
-                                    ]
-                                },
-                                "examples": {
-                                    "success": {
-                                        "description": "Parameters: `start_date=2022-01-01&end_date=2022-01-01&realm=SUPREMM&fields=nodes,cores`",
-                                        "value": {
-                                            "success": true,
-                                            "fields": [ "Cores", "Nodes" ],
-                                            "data": [ ["1", "1"], ["5", "1"], ["2304", "24"] ]
-                                        }
-                                    }
-                                }
-                            }
+                            "application/json-seq": {}
                         }
                     },
                     "400": {