Adding in public endpoint definitions.

packages/server/.gitignore

@@ -3,7 +3,6 @@ myapps/
 .env
 builder/*
 client/*
-public/
 db/dev.db/
 dist
 coverage/

packages/server/specs/generate.js

@@ -18,12 +18,54 @@ const options = {
         description: "Budibase Cloud API",
       },
       {
-        url: "http://localhost:10000/api/public/v1",
+        url: "{protocol}://{hostname}:10000/api/public/v1",
         description: "Budibase self hosted API",
       },
     ],
+    components: {
+      examples: {
+        row: {
+          value: {
+            _id: "ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4",
+            type: "row",
+            tableId: "ta_5b1649e42a5b41dea4ef7742a36a7a70",
+            name: "Mike",
+            age: 30,
+            relationship: [
+              {
+                primaryDisplay: "Joe",
+                _id: "ro_ta_...",
+              },
+            ],
+          },
+        },
+        table: {
+          value: {
+            _id: "ta_5b1649e42a5b41dea4ef7742a36a7a70",
+            name: "People",
+            schema: {
+              name: {
+                type: "string",
+                name: "name",
+              },
+              age: {
+                type: "number",
+                name: "age",
+              },
+              relationship: {
+                type: "link",
+                name: "relationship",
+                tableId: "ta_...",
+                fieldName: "relatedColumn",
+                relationshipType: "many-to-many",
+              },
+            },
+          },
+        },
+      },
+    },
   },
-  format: "json",
+  format: ".json",
   apis: [join(__dirname, "..", "src", "api", "routes", "public", "*.js")],
 }
 
@@ -47,8 +89,7 @@ function writeFile(output, { isJson } = {}) {
 }
 
 const outputJSON = swaggerJsdoc(options)
-options.format = "yaml"
+options.format = ".yaml"
 const outputYAML = swaggerJsdoc(options)
-console.log(outputYAML)
+writeFile(outputJSON, { isJson: true })
-writeFile(outputJSON)
 writeFile(outputYAML)

packages/server/specs/openapi.json

@@ -7,14 +7,56 @@
   },
   "servers": [
     {
-      "url": "https://budibase.app/api/public/v1",
+      "url": "http://budibase.app/api/public/v1",
       "description": "Budibase Cloud API"
     },
     {
-      "url": "http://localhost:10000/api/public/v1",
+      "url": "{protocol}://{hostname}:10000/api/public/v1",
       "description": "Budibase self hosted API"
     }
   ],
+  "components": {
+    "examples": {
+      "row": {
+        "value": {
+          "_id": "ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4",
+          "type": "row",
+          "tableId": "ta_5b1649e42a5b41dea4ef7742a36a7a70",
+          "name": "Mike",
+          "age": 30,
+          "relationship": [
+            {
+              "primaryDisplay": "Joe",
+              "_id": "ro_ta_..."
+            }
+          ]
+        }
+      },
+      "table": {
+        "value": {
+          "_id": "ta_5b1649e42a5b41dea4ef7742a36a7a70",
+          "name": "People",
+          "schema": {
+            "name": {
+              "type": "string",
+              "name": "name"
+            },
+            "age": {
+              "type": "number",
+              "name": "age"
+            },
+            "relationship": {
+              "type": "link",
+              "name": "relationship",
+              "tableId": "ta_...",
+              "fieldName": "relatedColumn",
+              "relationshipType": "many-to-many"
+            }
+          }
+        }
+      }
+    }
+  },
   "paths": {
     "/row/{tableId}/search": {
       "post": {
@@ -37,45 +79,95 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "string": {
+                  "query": {
                     "type": "object",
-                    "example": {
+                    "properties": {
-                      "columnName1": "value",
+                      "string": {
-                      "columnName2": "value"
+                        "type": "object",
-                    },
+                        "example": {
-                    "description": "A map of field name to the string to search for, this will look for rows that have a value starting with the string value.",
+                          "columnName1": "value",
-                    "additionalProperties": {
+                          "columnName2": "value"
-                      "type": "string",
+                        },
-                      "description": "The value to search for in the column."
+                        "description": "A map of field name to the string to search for, this will look for rows that have a value starting with the string value.",
+                        "additionalProperties": {
+                          "type": "string",
+                          "description": "The value to search for in the column."
+                        }
+                      },
+                      "fuzzy": {
+                        "type": "object",
+                        "description": "A fuzzy search, only supported by internal tables."
+                      },
+                      "range": {
+                        "type": "object",
+                        "description": "Searches within a range, the format of this must be columnName -> [low, high]."
+                      },
+                      "equal": {
+                        "type": "object",
+                        "description": "Searches for rows that have a column value that is exactly the value set."
+                      },
+                      "notEqual": {
+                        "type": "object",
+                        "description": "Searches for any row which does not contain the specified column value."
+                      },
+                      "empty": {
+                        "type": "object",
+                        "description": "Searches for rows which do not contain the specified column. The object should simply contain keys of the column names, these can map to any value."
+                      },
+                      "notEmpty": {
+                        "type": "object",
+                        "description": "Searches for rows which have the specified column."
+                      },
+                      "oneOf": {
+                        "type": "object",
+                        "description": "Searches for rows which have a column value that is any of the specified values. The format of this must be columnName -> [value1, value2]."
+                      }
                     }
                   },
-                  "fuzzy": {
+                  "paginate": {
-                    "type": "object",
+                    "type": "boolean",
-                    "description": "A fuzzy search, only supported by internal tables."
+                    "description": "Enables pagination, by default this is disabled."
                   },
-                  "range": {
+                  "bookmark": {
-                    "type": "object",
+                    "oneOf": [
-                    "description": "Searches within a range, the format of this must be columnName -> [low, high]."
+                      {
+                        "type": "string"
+                      },
+                      {
+                        "type": "integer"
+                      }
+                    ],
+                    "description": "If retrieving another page, the bookmark from the previous request must be supplied."
                   },
-                  "equal": {
+                  "limit": {
-                    "type": "object",
+                    "type": "integer",
-                    "description": "Searches for rows that have a column value that is exactly the value set."
+                    "description": "The maximum number of rows to return, useful when paginating, for internal tables this will be limited to 1000, for SQL tables it will be 5000."
                   },
-                  "notEqual": {
+                  "sort": {
                     "type": "object",
-                    "description": "Searches for any row which does not contain the specified column value."
+                    "description": "A set of parameters describing the sort behaviour of the search.",
-                  },
+                    "properties": {
-                  "empty": {
+                      "order": {
-                    "type": "object",
+                        "type": "string",
-                    "description": "Searches for rows which do not contain the specified column. The object should simply contain keys of the column names, these can map to any value."
+                        "enum": [
-                  },
+                          "ascending",
-                  "notEmpty": {
+                          "descending"
-                    "type": "object",
+                        ],
-                    "description": "Searches for rows which have the specified column."
+                        "description": "The order of the sort, by default this is ascending."
-                  },
+                      },
-                  "oneOf": {
+                      "column": {
-                    "type": "object",
+                        "type": "string",
-                    "description": "Searches for rows which have a column value that is any of the specified values. The format of this must be columnName -> [value1, value2]."
+                        "description": "The name of the column by which the rows will be sorted."
+                      },
+                      "type": {
+                        "type": "string",
+                        "enum": [
+                          "string",
+                          "number"
+                        ],
+                        "description": "Defines whether the column should be treated as a string or as numbers when sorting."
+                      }
+                    }
                   }
                 }
               }
@@ -84,12 +176,45 @@
         },
         "responses": {
           "200": {
-            "description": "Returns the rows."
+            "description": "The response will contain an array of rows that match the search parameters.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "rows": {
+                      "description": "An array of rows, these will each contain an _id field which can be used to update or delete them.",
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "example": {
+                          "$ref": "#/components/examples/row"
+                        }
+                      }
+                    },
+                    "bookmark": {
+                      "oneOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "integer"
+                        }
+                      ],
+                      "description": "If pagination in use, this should be provided"
+                    },
+                    "hasNextPage": {
+                      "description": "If pagination in use, this will determine if there is another page to fetch.",
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
           }
         }
       }
     }
   },
-  "components": {},
   "tags": []
 }

packages/server/specs/openapi.yaml

@@ -0,0 +1,160 @@
+openapi: 3.0.0
+info:
+  title: Budibase API
+  description: The public API for Budibase apps and its services.
+  version: 1.0.0
+servers:
+  - url: http://budibase.app/api/public/v1
+    description: Budibase Cloud API
+  - url: "{protocol}://{hostname}:10000/api/public/v1"
+    description: Budibase self hosted API
+components:
+  examples:
+    row:
+      value:
+        _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
+        type: row
+        tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
+        name: Mike
+        age: 30
+        relationship:
+          - primaryDisplay: Joe
+            _id: ro_ta_...
+    table:
+      value:
+        _id: ta_5b1649e42a5b41dea4ef7742a36a7a70
+        name: People
+        schema:
+          name:
+            type: string
+            name: name
+          age:
+            type: number
+            name: age
+          relationship:
+            type: link
+            name: relationship
+            tableId: ta_...
+            fieldName: relatedColumn
+            relationshipType: many-to-many
+paths:
+  "/row/{tableId}/search":
+    post:
+      summary: Allows searching for rows within a table.
+      parameters:
+        - in: path
+          name: tableId
+          required: true
+          description: The ID of the table which contains the rows which are being
+            searched for.
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                query:
+                  type: object
+                  properties:
+                    string:
+                      type: object
+                      example:
+                        columnName1: value
+                        columnName2: value
+                      description: A map of field name to the string to search for, this will look for
+                        rows that have a value starting with the string value.
+                      additionalProperties:
+                        type: string
+                        description: The value to search for in the column.
+                    fuzzy:
+                      type: object
+                      description: A fuzzy search, only supported by internal tables.
+                    range:
+                      type: object
+                      description: Searches within a range, the format of this must be columnName ->
+                        [low, high].
+                    equal:
+                      type: object
+                      description: Searches for rows that have a column value that is exactly the
+                        value set.
+                    notEqual:
+                      type: object
+                      description: Searches for any row which does not contain the specified column
+                        value.
+                    empty:
+                      type: object
+                      description: Searches for rows which do not contain the specified column. The
+                        object should simply contain keys of the column names,
+                        these can map to any value.
+                    notEmpty:
+                      type: object
+                      description: Searches for rows which have the specified column.
+                    oneOf:
+                      type: object
+                      description: Searches for rows which have a column value that is any of the
+                        specified values. The format of this must be columnName
+                        -> [value1, value2].
+                paginate:
+                  type: boolean
+                  description: Enables pagination, by default this is disabled.
+                bookmark:
+                  oneOf:
+                    - type: string
+                    - type: integer
+                  description: If retrieving another page, the bookmark from the previous request
+                    must be supplied.
+                limit:
+                  type: integer
+                  description: The maximum number of rows to return, useful when paginating, for
+                    internal tables this will be limited to 1000, for SQL tables
+                    it will be 5000.
+                sort:
+                  type: object
+                  description: A set of parameters describing the sort behaviour of the search.
+                  properties:
+                    order:
+                      type: string
+                      enum:
+                        - ascending
+                        - descending
+                      description: The order of the sort, by default this is ascending.
+                    column:
+                      type: string
+                      description: The name of the column by which the rows will be sorted.
+                    type:
+                      type: string
+                      enum:
+                        - string
+                        - number
+                      description: Defines whether the column should be treated as a string or as
+                        numbers when sorting.
+      responses:
+        "200":
+          description: The response will contain an array of rows that match the search
+            parameters.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  rows:
+                    description: An array of rows, these will each contain an _id field which can be
+                      used to update or delete them.
+                    type: array
+                    items:
+                      type: object
+                      example:
+                        $ref: "#/components/examples/row"
+                  bookmark:
+                    oneOf:
+                      - type: string
+                      - type: integer
+                    description: If pagination in use, this should be provided
+                  hasNextPage:
+                    description: If pagination in use, this will determine if there is another page
+                      to fetch.
+                    type: boolean
+tags: []

packages/server/src/api/controllers/public/index.js

@@ -0,0 +1,24 @@
+/*
+ * Contains pass through functions for all of the public API, make sure
+ * parameters are in correct format for the main controllers.
+ */
+
+exports.search = () => {
+
+}
+
+exports.create = () => {
+
+}
+
+exports.singleRead = () => {
+
+}
+
+exports.update = () => {
+
+}
+
+exports.delete = () => {
+
+}

packages/server/src/api/routes/public/applications.js

@@ -0,0 +1,5 @@
+const Router = require("@koa/router")
+
+const router = Router()
+
+module.exports = router

packages/server/src/api/routes/public/index.js

@@ -0,0 +1,25 @@
+const appRoute = require("./applications")
+const queryRoute = require("./queries")
+const tableRoute = require("./tables")
+const rowRoute = require("./rows")
+const userRoute = require("./users")
+const Router = require("@koa/router")
+
+const PREFIX = "/api/public/v1"
+const ROUTES = [
+  appRoute,
+  queryRoute,
+  tableRoute,
+  rowRoute,
+  userRoute
+]
+
+const router = new Router({
+  prefix: PREFIX,
+})
+for (let route of ROUTES) {
+  router.use(route.routes())
+  router.use(route.allowedMethods())
+}
+
+module.exports = router

packages/server/src/api/routes/public/queries.js

@@ -0,0 +1,5 @@
+const Router = require("@koa/router")
+
+const router = Router()
+
+module.exports = router

packages/server/src/api/routes/public/rows.js

@@ -0,0 +1,130 @@
+const Router = require("@koa/router")
+const controller = require("../../controllers/public")
+
+const router = Router()
+
+/**
+ * @openapi
+ * /row/{tableId}/search:
+ *   post:
+ *     summary: Allows searching for rows within a table.
+ *     parameters:
+ *       - in: path
+ *         name: tableId
+ *         required: true
+ *         description: The ID of the table which contains the rows
+ *           which are being searched for.
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               query:
+ *                 type: object
+ *                 properties:
+ *                   string:
+ *                     type: object
+ *                     example:
+ *                       columnName1: value
+ *                       columnName2: value
+ *                     description: A map of field name to the string to search for,
+ *                       this will look for rows that have a value starting with the
+ *                       string value.
+ *                     additionalProperties:
+ *                       type: string
+ *                       description: The value to search for in the column.
+ *                   fuzzy:
+ *                     type: object
+ *                     description: A fuzzy search, only supported by internal tables.
+ *                   range:
+ *                     type: object
+ *                     description: Searches within a range, the format of this must be
+ *                       columnName -> [low, high].
+ *                   equal:
+ *                     type: object
+ *                     description: Searches for rows that have a column value that is
+ *                       exactly the value set.
+ *                   notEqual:
+ *                     type: object
+ *                     description: Searches for any row which does not contain the specified
+ *                       column value.
+ *                   empty:
+ *                     type: object
+ *                     description: Searches for rows which do not contain the specified column.
+ *                       The object should simply contain keys of the column names, these
+ *                       can map to any value.
+ *                   notEmpty:
+ *                     type: object
+ *                     description: Searches for rows which have the specified column.
+ *                   oneOf:
+ *                     type: object
+ *                     description: Searches for rows which have a column value that is any
+ *                       of the specified values. The format of this must be columnName -> [value1, value2].
+ *               paginate:
+ *                 type: boolean
+ *                 description: Enables pagination, by default this is disabled.
+ *               bookmark:
+ *                 oneOf:
+ *                   - type: string
+ *                   - type: integer
+ *                 description: If retrieving another page, the bookmark from the previous request must be supplied.
+ *               limit:
+ *                 type: integer
+ *                 description: The maximum number of rows to return, useful when paginating, for internal tables this
+ *                   will be limited to 1000, for SQL tables it will be 5000.
+ *               sort:
+ *                 type: object
+ *                 description: A set of parameters describing the sort behaviour of the search.
+ *                 properties:
+ *                   order:
+ *                     type: string
+ *                     enum: [ascending, descending]
+ *                     description: The order of the sort, by default this is ascending.
+ *                   column:
+ *                     type: string
+ *                     description: The name of the column by which the rows will be sorted.
+ *                   type:
+ *                     type: string
+ *                     enum: [string, number]
+ *                     description: Defines whether the column should be treated as a string
+ *                       or as numbers when sorting.
+ *     responses:
+ *       200:
+ *         description: The response will contain an array of rows that match the search parameters.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 rows:
+ *                   description: An array of rows, these will each contain an _id field which can be used
+ *                     to update or delete them.
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     example:
+ *                       $ref: '#/components/examples/row'
+ *                 bookmark:
+ *                   oneOf:
+ *                     - type: string
+ *                     - type: integer
+ *                   description: If pagination in use, this should be provided
+ *                 hasNextPage:
+ *                   description: If pagination in use, this will determine if there is another page to fetch.
+ *                   type: boolean
+ */
+router.post("/tables/:tableId/rows/search", controller.search)
+
+router.post("/tables/:tableId/rows", controller.create)
+
+router.put("/tables/:tableId/rows/:rowId", controller.update)
+
+router.delete("/tables/:tableId/rows/:rowId", controller.delete)
+
+router.get("/tables/:tableId/rows/:rowId", controller.singleRead)
+
+module.exports = router

packages/server/src/api/routes/public/tables.js

@@ -0,0 +1,5 @@
+const Router = require("@koa/router")
+
+const router = Router()
+
+module.exports = router

packages/server/src/api/routes/public/users.js

@@ -0,0 +1,5 @@
+const Router = require("@koa/router")
+
+const router = Router()
+
+module.exports = router