JSON DB API

Master list of JSON DB API actions for managing FairCom databases, tables, indexes, records, cursors, SQL, and transactions

Abstract

The JSON DB API manages a FairCom database. It provides actions to manage databases, tables, indexes, records, cursors, SQL, and transactions.

This API is based on the jsonAction protocol, which POSTs JSON requests to one endpoint on a server and returns JSON responses. This section defines the JSON payloads that can be POSTed to the FairCom server over HTTP, HTTPS, WS, and WSS using the endpoint /api, such as https://localhost:8443/api.

Sessions

These actions are part of the Admin API and are used by all FairCom APIs. They are used to log in and log out of the server.

Action	Description
`"alterSession"`	Modifies the settings of a session, such as changing the default database and owner.
`"createSession"`	Allows an account to log into a FairCom server.
`"deleteSession"`	Allows an account to logout and close a session.
`"describeSessions"`	Describes the settings for one or more sessions.
`"listSessions"`	Lists sessions that the current account is authorized to see.
`"pingSession"`	Keeps a session alive and returns failure when a session is inactive.

Services

These actions are part of the Admin API and are used by all FairCom's APIs. They are used to manage services.

Action	Description
`"listServices"`	Returns information about each specified service.
`"manageService"`	Configures the general settings of a FairCom server service.

Databases

Action	Description
`"createDatabase"`	`"createDatabase"` creates a database.
`"deleteDatabase"`	`"deleteDatabase"` deletes a database unless archived, deleting a database and its containing folder and all its files . It removes all data and metadata in the database.
`"listDatabases"`	`"listDatabses"` lists databases the logged-in user is allowed to see.

Tables

Action	Description
`"alterTable"`	`"alterTable"` modifies a table.
`"createTable"`	`"createTable"` creates a table in a database.
`"deleteTables"`	`"deleteTables"` deletes one or more tables in a single transaction.
`"describeTables"`	`"describeTables"` returns a complete set of metadata about one or more specified tables.
`"listTables"`	`"listTables"` lists tables in the specified database that the logged-in user is allowed to see.
`"rebuildTables"`	`"rebuildTables"` rebuilds specified tables.

Indexes

Action	Description
`"createIndex"`	`"createIndex"` creates an index on one or more fields in a table.
`"deleteIndexes"`	`"deleteIndexes"` deletes an index.
`"listIndexes"`	`"listIndexes"` lists indexes in the specified database table that the logged-in user is allowed to see.
`"rebuildIndexes"`	`"rebuildIndexes"` rebuilds all indexes or specified indexes.

Modify data

Action	Description
`"deleteRecords"`	`"deleteRecords"` deletes one or more records from a database table using one or more IDs.
`"insertRecords"`	`"insertRecords"` inserts one or more records into a database table - one record for each item in the `"data"` array.
`"truncateRecords"`	`"truncateRecords"` deletes all records from a database table very quickly by deleting and recreating the data file.
`"updateRecords"`	`"updateRecords"` updates one or more records in a database table.

Get data

Action	Description
`"closeCursor"`	`"closeCursor"` closes a previously opened cursor.
`"getRecordsByIds"`	`"getRecordsByIds"` retrieves one or more records from a database using their IDs. This action is useful for using the database as a simple key-value store.
`"getRecordsByIndex"`	`"getRecordsByIndex"` can return a cursor that quickly retrieves records forward and backward in index order. The cursor can efficiently retrieve thousands of records at a time. The cursor can fetch records forward and backward and skip past records.
`"getRecordsByPartialKeyRange"`	`"getRecordsByPartialKeyRange"` retrieves records from a database table that match a partial key in the specified index. It is particularly useful for typeahead queries.
`"getRecordsByTable"`	`"getRecordsByTable"` retrieves records from a database table in table order. It can return a cursor that quickly and efficiently paginates through records in the table. It can also immediately return all records in a table.
`"getRecordsFromCursor"`	`"getRecordsFromCursor"` retrieves records from a cursor returned from another "getRecords..." action. A cursor can efficiently retrieve thousands of records at a time. Most cursors can fetch records forward and backward and skip past records.
`"getRecordsInKeyRange"`	`"getRecordsInKeyRange"` retrieves records from a database table within a specified range of keys in an index. It matches index keys against partial or complete key values. The upper or lower bounds of the key range can be specified or omitted. This action is the fastest way to retrieve a bounded set of records in index order.
`"getRecordsStartingAtKey"`	`"getRecordsStartingAtKey"` retrieves records from a database table starting with the record that most closely matches the specified key in the specified index. It is the fastest way to walk records in index order starting at a specific key. It is typically used to look up records that are near a key. It can also be used to retrieve a span of records before and after a key value.
`"getRecordsUsingSQL"`	`"getRecordsUsingSQL"` uses SQL to retrieve records. It can return a cursor that retrieves records forward and backward in SQL query order. The cursor can efficiently retrieve thousands of records at a time. The cursor can fetch records forward and backward and skip past records.

SQL

Action	Description
`"getRecordsUsingSQL"`	`"getRecordsUsingSQL"` uses SQL to retrieve a set of records.
`"runSqlStatements"`	`"runSqlStatements"` runs one or more SQL statements, such as drop, create, alter, call, insert, update, and delete statements.

Transactions

Action	Description
`"commitTransaction"`	This closes a transaction and makes its changes durable and visible to other transactions. You can include the `"transactionSavepointId"` property to commit changes in the transaction up to the savepoint. `"commitTransaction"` always closes a transaction. Once a transaction is closed, you can no longer use its `"transactionId"`.
`"createTransaction"`	This returns a `"transactionId"` property that you can add to other actions to put them under control of this transaction. Until you run `"commitTransaction"`, changes made inside the transaction are invisible outside the transaction and are not durably persisted; thus, if the server fails before the transaction commits, all actions in the transaction are automatically rolled back.
`"createTransactionSavePoint"`	This bookmarks the current point in the transaction process. You can create multiple savepoints and use `"revertTransactionToSavepoint"` to undo changes made after the savepoint.
`"listTransactions"`	This returns a list of all active transactions that the logged-in account is authorized to see.
`"rollbackTransaction"`	This closes a transaction and discards all changes made under the control of the transaction. Once a transaction is closed, you can no longer use its `"transactionId"`.
`"revertTransactionToSavepoint"`	This undoes a transaction's changes back to a savepoint previously created by `"createTransactionSavepoint"` . It keeps the transaction open so you can continue to do more actions under transaction control.

JSON requestsJSON responses