771 lines
25 KiB
YAML
771 lines
25 KiB
YAML
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:
|
|
parameters:
|
|
tableId:
|
|
in: path
|
|
name: tableId
|
|
required: true
|
|
description: The ID of the table which this request is targeting.
|
|
schema:
|
|
type: string
|
|
rowId:
|
|
in: path
|
|
name: rowId
|
|
required: true
|
|
description: The ID of the row which this request is targeting.
|
|
schema:
|
|
type: string
|
|
appId:
|
|
in: header
|
|
name: x-budibase-app-id
|
|
required: true
|
|
description: The ID of the app which this request is targeting.
|
|
schema:
|
|
type: string
|
|
appIdUrl:
|
|
in: path
|
|
name: appId
|
|
required: true
|
|
description: The ID of the app which this request is targeting.
|
|
schema:
|
|
type: string
|
|
queryId:
|
|
in: path
|
|
name: queryId
|
|
required: true
|
|
description: The ID of the query which this request is targeting.
|
|
schema:
|
|
type: string
|
|
userId:
|
|
in: path
|
|
name: userId
|
|
required: true
|
|
description: The ID of the user which this request is targeting.
|
|
schema:
|
|
type: string
|
|
examples:
|
|
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
|
|
tables:
|
|
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
|
|
inputRow:
|
|
value:
|
|
_id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
|
|
type: row
|
|
tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
|
|
name: Mike
|
|
age: 30
|
|
relationship:
|
|
- ro_ta_...
|
|
row:
|
|
value:
|
|
_id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
|
|
type: row
|
|
tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
|
|
name: Mike
|
|
age: 30
|
|
relationship:
|
|
- primaryDisplay: Joe
|
|
_id: ro_ta_...
|
|
search:
|
|
value:
|
|
rows:
|
|
- _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
|
|
type: row
|
|
tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
|
|
name: Mike
|
|
age: 30
|
|
relationship:
|
|
- primaryDisplay: Joe
|
|
_id: ro_ta_...
|
|
hasNextPage: true
|
|
bookmark: 10
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: x-budibase-api-key
|
|
description: Your individual API key, this will provide access based on the
|
|
configured RBAC settings of your user.
|
|
schemas:
|
|
row:
|
|
description: The row to be created/updated, based on the table schema.
|
|
type: object
|
|
additionalProperties:
|
|
oneOf:
|
|
- type: string
|
|
- type: object
|
|
- type: integer
|
|
- type: array
|
|
- type: boolean
|
|
table:
|
|
description: The table to be created/updated.
|
|
type: object
|
|
properties:
|
|
name:
|
|
description: The name of the table
|
|
type: string
|
|
primaryDisplay:
|
|
type: string
|
|
description: The name of the column which should be used in relationship tags
|
|
when relating to this table.
|
|
schema:
|
|
oneOf:
|
|
- type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- link
|
|
description: A relationship column.
|
|
constraints:
|
|
type: object
|
|
description: A constraint can be applied to the column which will be validated
|
|
against when a row is saved.
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- string
|
|
- number
|
|
- object
|
|
- boolean
|
|
presence:
|
|
type: boolean
|
|
description: Defines whether the column is required or not.
|
|
name:
|
|
type: string
|
|
description: The name of the column.
|
|
autocolumn:
|
|
type: boolean
|
|
description: Defines whether the column is automatically generated.
|
|
fieldName:
|
|
type: string
|
|
description: The name of the column which a relationship column is related to in
|
|
another table.
|
|
tableId:
|
|
type: string
|
|
description: The ID of the table which a relationship column is related to.
|
|
relationshipType:
|
|
type: string
|
|
enum:
|
|
- one-to-many
|
|
- many-to-one
|
|
- many-to-many
|
|
description: Defines the type of relationship that this column will be used for.
|
|
through:
|
|
type: string
|
|
description: When using a SQL table that contains many to many relationships
|
|
this defines the table the relationships are linked through.
|
|
foreignKey:
|
|
type: string
|
|
description: When using a SQL table that contains a one to many relationship
|
|
this defines the foreign key.
|
|
throughFrom:
|
|
type: string
|
|
description: When using a SQL table that utilises a through table, this defines
|
|
the primary key in the through table for this table.
|
|
throughTo:
|
|
type: string
|
|
description: When using a SQL table that utilises a through table, this defines
|
|
the primary key in the through table for the related table.
|
|
- type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- formula
|
|
description: A formula column.
|
|
constraints:
|
|
type: object
|
|
description: A constraint can be applied to the column which will be validated
|
|
against when a row is saved.
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- string
|
|
- number
|
|
- object
|
|
- boolean
|
|
presence:
|
|
type: boolean
|
|
description: Defines whether the column is required or not.
|
|
name:
|
|
type: string
|
|
description: The name of the column.
|
|
autocolumn:
|
|
type: boolean
|
|
description: Defines whether the column is automatically generated.
|
|
formula:
|
|
type: string
|
|
description: Defines a Handlebars or JavaScript formula to use, note that
|
|
Javascript formulas are expected to be provided in the
|
|
base64 format.
|
|
formulaType:
|
|
type: string
|
|
enum:
|
|
- static
|
|
- dynamic
|
|
description: Defines whether this is a static or dynamic formula.
|
|
- type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- string
|
|
- longform
|
|
- options
|
|
- number
|
|
- boolean
|
|
- array
|
|
- datetime
|
|
- attachment
|
|
- link
|
|
- formula
|
|
- auto
|
|
- json
|
|
- internal
|
|
description: Defines the type of the column, most explain themselves, a link
|
|
column is a relationship.
|
|
constraints:
|
|
type: object
|
|
description: A constraint can be applied to the column which will be validated
|
|
against when a row is saved.
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum:
|
|
- string
|
|
- number
|
|
- object
|
|
- boolean
|
|
presence:
|
|
type: boolean
|
|
description: Defines whether the column is required or not.
|
|
name:
|
|
type: string
|
|
description: The name of the column.
|
|
autocolumn:
|
|
type: boolean
|
|
description: Defines whether the column is automatically generated.
|
|
query:
|
|
type: object
|
|
properties: {}
|
|
user:
|
|
type: object
|
|
properties: {}
|
|
application:
|
|
type: object
|
|
properties: {}
|
|
security:
|
|
- ApiKeyAuth: []
|
|
paths:
|
|
/applications/search:
|
|
post:
|
|
summary: Search for an application based on its app name.
|
|
tags:
|
|
- applications
|
|
parameters:
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the applications that were found based on the search
|
|
parameters.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/application"
|
|
/applications:
|
|
post:
|
|
summary: Create a new application.
|
|
tags:
|
|
- applications
|
|
parameters:
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the created application.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
"/applications/{appId}":
|
|
put:
|
|
summary: Update an existing application by its ID.
|
|
tags:
|
|
- applications
|
|
parameters:
|
|
- $ref: "#/components/parameters/appIdUrl"
|
|
responses:
|
|
"200":
|
|
description: Returns the updated application.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
delete:
|
|
summary: Delete an existing application by its ID.
|
|
tags:
|
|
- applications
|
|
parameters:
|
|
- $ref: "#/components/parameters/appIdUrl"
|
|
responses:
|
|
"200":
|
|
description: Returns the deleted application.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
/queries/search:
|
|
post:
|
|
summary: Search for a query based on its name.
|
|
tags:
|
|
- queries
|
|
parameters:
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the queries found based on the search parameters.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/query"
|
|
"/queries/{queryId}":
|
|
post:
|
|
summary: Execute a query and retrieve its response.
|
|
tags:
|
|
- queries
|
|
parameters:
|
|
- $ref: "#/components/parameters/queryId"
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the result of the query execution.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
"/tables/{tableId}/rows/search":
|
|
post:
|
|
summary: Used to search for rows within a table.
|
|
tags:
|
|
- rows
|
|
parameters:
|
|
- $ref: "#/components/parameters/tableId"
|
|
- $ref: "#/components/parameters/appId"
|
|
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].
|
|
example:
|
|
columnName1:
|
|
- 10
|
|
- 20
|
|
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.
|
|
example:
|
|
columnName1: ""
|
|
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
|
|
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
|
|
examples:
|
|
search:
|
|
$ref: "#/components/examples/search"
|
|
"/tables/{tableId}/rows":
|
|
post:
|
|
summary: Creates a new row within a specified table.
|
|
tags:
|
|
- rows
|
|
parameters:
|
|
- $ref: "#/components/parameters/tableId"
|
|
- $ref: "#/components/parameters/appId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/row"
|
|
examples:
|
|
row:
|
|
$ref: "#/components/examples/inputRow"
|
|
responses:
|
|
"200":
|
|
description: Returns the created row, including the ID which has been generated
|
|
for it. This can be found in the Budibase portal, viewed under the
|
|
developer information.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
row:
|
|
$ref: "#/components/examples/row"
|
|
"/tables/{tableId}/rows/{rowId}":
|
|
put:
|
|
summary: Update a single row within a specified table.
|
|
tags:
|
|
- rows
|
|
parameters:
|
|
- $ref: "#/components/parameters/tableId"
|
|
- $ref: "#/components/parameters/rowId"
|
|
- $ref: "#/components/parameters/appId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/row"
|
|
examples:
|
|
row:
|
|
$ref: "#/components/examples/inputRow"
|
|
responses:
|
|
"200":
|
|
description: Returns the created row, including the ID which has been generated
|
|
for it.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
row:
|
|
$ref: "#/components/examples/row"
|
|
delete:
|
|
summary: Delete a single row from the specified table.
|
|
tags:
|
|
- rows
|
|
parameters:
|
|
- $ref: "#/components/parameters/tableId"
|
|
- $ref: "#/components/parameters/rowId"
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the deleted row, including the ID which has been generated
|
|
for it.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
row:
|
|
$ref: "#/components/examples/row"
|
|
get:
|
|
summary: Get a single row from the specified table.
|
|
tags:
|
|
- rows
|
|
parameters:
|
|
- $ref: "#/components/parameters/tableId"
|
|
- $ref: "#/components/parameters/rowId"
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the retrieved row.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
row:
|
|
$ref: "#/components/examples/row"
|
|
/tables/search:
|
|
post:
|
|
summary: Search internal and external tables based on their name.
|
|
tags:
|
|
- tables
|
|
parameters:
|
|
- $ref: "#/components/parameters/appId"
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The name of the table, this is a case insensitive search using the
|
|
provided name as a starts with search.
|
|
responses:
|
|
"200":
|
|
description: Returns the found tables, based on the search parameters.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
examples:
|
|
tables:
|
|
$ref: "#/components/examples/tables"
|
|
/tables:
|
|
post:
|
|
summary: Create a new table.
|
|
tags:
|
|
- tables
|
|
parameters:
|
|
- $ref: "#/components/parameters/appId"
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/table"
|
|
examples:
|
|
table:
|
|
$ref: "#/components/examples/table"
|
|
responses:
|
|
"200":
|
|
description: Returns the created table, including the ID which has been
|
|
generated for it. This can be internal or external data sources.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
table:
|
|
$ref: "#/components/examples/table"
|
|
/tables/:tableId:
|
|
put:
|
|
summary: Update the specified table. This can be for internal or external tables.
|
|
tags:
|
|
- tables
|
|
parameters:
|
|
- $ref: "#/components/parameters/tableId"
|
|
- $ref: "#/components/parameters/appId"
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/table"
|
|
examples:
|
|
table:
|
|
$ref: "#/components/examples/table"
|
|
responses:
|
|
"200":
|
|
description: Returns the updated table.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
table:
|
|
$ref: "#/components/examples/row"
|
|
"/tables/{tableId}":
|
|
delete:
|
|
summary: Delete a single table and all of its data.
|
|
tags:
|
|
- tables
|
|
parameters:
|
|
- $ref: "#/components/parameters/tableId"
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the deleted table.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
examples:
|
|
table:
|
|
$ref: "#/components/examples/table"
|
|
/users/search:
|
|
post:
|
|
summary: Search for a user based on their email/username.
|
|
tags:
|
|
- users
|
|
parameters:
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the found users based on search parameters.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/user"
|
|
/users:
|
|
post:
|
|
summary: Create a new user in the Budibase portal.
|
|
tags:
|
|
- users
|
|
parameters:
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the created user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
"/users/{userId}":
|
|
put:
|
|
summary: Update an existing user by their ID.
|
|
tags:
|
|
- users
|
|
parameters:
|
|
- $ref: "#/components/parameters/userId"
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the updated user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
delete:
|
|
summary: Delete an existing user by their ID.
|
|
tags:
|
|
- users
|
|
parameters:
|
|
- $ref: "#/components/parameters/userId"
|
|
- $ref: "#/components/parameters/appId"
|
|
responses:
|
|
"200":
|
|
description: Returns the deleted user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
tags: []
|