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 the JSON request to one endpoint on a server and returns the JSON response. 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.
There are properties that are universally used within every action of each jsonAction request and response message. For a comprehensive explanation and multiple examples of these properties, see JSON Action REST 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 | 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 | 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 | bookmarks the current point in the transaction process. You can create multiple savepoints and use "revertTransactionToSavepoint" to undo changes made after the savepoint. |
| listTransactions | returns a list of all active transactions that the logged-in account is authorized to see. |
| rollbackTransaction | 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 | reverts a transaction back to a savepoint previously created by "createTransactionSavepoint" . It keeps the transaction open so you can continue to do more actions under transaction control. |
Data Change Stream (DCS)
Manage connection actions
| Action | Description |
|---|---|
| alterStreamingConnection | Alters connection settings to a FairCom DB or RTG server. |
| createStreamingConnection | Creates a connection to a FairCom DB or RTG server. |
| deleteStreamingConnection | Deletes a connection to a FairCom DB or RTG server. Before you delete a connection, you must pause all data change streams that use it. |
| listStreamingConnectionProblems | Lists streaming connections that match the problem filters in the request. |
| listStreamingConnections | Lists existing streaming connections and fully describes each one. |
| pauseStreamingConnection | Pauses all data change streams in the specified connection. |
| resumeStreamingConnection | Resumes all data change streams in the specified connection. |
Run stream actions
| Action | Description |
|---|---|
| createAndStartDataChangeStream | Starts one data change stream and returns the unique ID of the stream along with all its properties. |
| deleteDataChangeStreams | Permanently deletes one or more data change streams specified by their IDs. |
| listDataChangeStreams | Returns a filtered list of data change streams. Each stream includes its ID and description. |
| describeDataChangeStreams | Returns specified data change streams with all their properties. |