You configure FairCom Edge using the JSON Hub API.
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.
The following sections list all available actions for configuring FairCom Edge.
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.
This API also requires using jsonActions that are in the Admin API — for example, the admin "createSession" action is used to log into the server. For a comprehensive explanation and multiple examples of these actions, see admin api.
Note that integration tables are an enhanced form of normal tables. The JSON DB API only manages normal tables. To manage Integration tables, see the integration table actions in the JSON Hub API.
Note When using the Property summary tables, if there is additional information that the Property summary tables do not provide the property has a link to the property topic that contains the comprehensive explanation.
| Action group | API |
|---|---|
| Sessions | Admin API |
| Services | Admin API |
| Inputs | Hub API |
| Outputs | Hub API |
| Code packages | Admin API |
| Integration tables | Hub API |
| MQTT Topics | MQ API |
| Broker connections | MQ API |
| Databases | DB API |
| Tables | DB API |
| Indexes | DB API |
| Modify data | DB API |
| Get data | DB API |
| Data Change Stream | MQ API |
Sessions
These actions 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 used to manage services.
| Action | Description |
|---|---|
| listServices | Returns information about each specified service. |
| manageService | Configures the general settings of a FairCom server service. |
Inputs
These actions alter, create, delete, describe, and list inputs. An input is a connection to an external device, equipment, or service that can input data into FairCom Edge. The input allows you to configure the connection, such as the frequency of data collection and the tags to be collected.
| Action | Description |
|---|---|
| alterInput | alters, changes, modifies, updates, or configures an existing input connector in FairCom Edge. An input connector collects data automatically from a device or software system. |
| createInput | creates a new input. |
| deleteInput | removes a previously created input definition as long as no output definitions are using it. |
| describeInputs | returns all available information about each specified input. |
| listInputs | obtains a list of names of previously created inputs. |
Outputs
These actions create, alter, delete, describe, and list outputs. An output delivers data collected by FairCom Edge to external services, such as a REST service, ThingWorx, OPC UA, etc.
| Action | Description |
|---|---|
| alterOutput |
|
| createOutput |
|
| deleteOutput |
|
| describeOutputs |
|
| listOutputs |
|
Code packages
These actions create, alter, describe, list, clone, and revert code packages or their histories.
Note There is no action to delete a code package. To deactivate a code package, set the
"codeStatus"property to"deleted","inactive", or"deprecated".If you want to update a code package, you can call the
"alterCodePackage"action using the name of a code package that has already been created.
| Action | Description |
|---|---|
| createCodePackage |
"createCodePackage" stores JavaScript code in the server. |
| alterCodePackage |
"alterCodePackage" updates a package's code and optional metadata. |
| describeCodePackages |
"describeCodePackages" returns all the current information about the specified code package names including source code and package properties. |
| describeCodePackageHistory |
"describeCodePackageHistory" returns historical versions of the code package, including code and metadata. |
| listCodePackages |
"listCodePackages" returns a list of code packages that match all specified filters. |
| listCodePackageHistory |
"listCodePackageHistory" returns a list of code packages from the code package history that match all the specified filters. |
| cloneCodePackage |
"cloneCodePackage" creates a new code package with a new name and copies an existing code package into it. |
| revertCodePackage |
"revertCodePackage" provides a fast way to revert back to a known good version when new code is not working well. |
Integration tables
These actions create, alter, delete, describe, and list integration tables.
Note Integration tables are an enhanced form of normal tables. Integration tables contain extra fields to timestamp and transform inserted records. They also can forward data to output services with guaranteed delivery. See the JSON DB API to manage normal tables.
| Action | Description |
|---|---|
| alterIntegrationTable | alters table settings that are safe to modify, such as adding new fields |
| copyIntegrationTableTransformSteps | replaces a target table's transform steps |
| createIntegrationTable | creates an integration table |
| deleteIntegrationTables | deletes an integration table as long as there are no dependencies on it |
| describeIntegrationTables | returns all available information about each specified integration table |
| listIntegrationTables | lists only the integration tables in a given database |
| rerunIntegrationTableTransformSteps | reruns transform steps after updating them |
| testIntegrationTableTransformSteps | tests new transform steps before running them |
MQTT Topics
This section provides several actions to configure, delete, describe, and list MQTT topics.
| Action | Description |
|---|---|
| configureTopic |
|
| deleteTopic |
|
| describeTopics |
|
| listTopics |
|
Broker connections
The broker connection actions configure, delete, describe, and list broker connections.
| Action | Description |
|---|---|
| configureBrokerConnection |
|
| deleteBrokerConnection |
|
| describeBrokerConnections |
|
| listBrokerConnections |
|
Databases
These actions create, delete, and list 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
These actions create, alter, delete, describe, list, and rebuild tables.
Note Integration tables are an enhanced form of normal tables. The JSON DB API only manages normal tables. To manage Integration tables, see the integration table actions in the JSON Hub API.
| 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
These actions create, delete, describe, and list 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
These actions insert, update, and delete, records in tables. You can also truncate a table that is not in use to quickly remove all records in a table.
| 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
These actions query records in tables. Most actions can directly return data or return a cursor that you can use to paginate forward and backward through the records. You can look up records by ID, find records that most closely match a key, retrieve all records in a table, retrieve records in index order, retrieve records within a key range, and retrieve records returned by a SQL query. These actions work with all tables, including FairCom Edge's integration tables.
| Action | Description |
|---|---|
| closeCursor |
"closeCursor" closes a previously opened cursor. |
| getRecordsByIds |
This action treats a table as a simple key-value store when the primary key is the This action is the fastest way to retrieve records by ID or a multi-field primary key. |
| getRecordsByIndex |
This action can also efficiently return all records in one call when the table contains tens of thousands of records. The records can be sorted forward or backward in index order. |
| getRecordsByPartialKeyRange |
This action can efficiently return all matching records in one call, which is helpful for typeahead queries. The records are sorted forward or backward in index order. It can also return a cursor when you expect matching records to exceed tens of thousands of records. |
| getRecordsByTable |
This action is the fastest way to retrieve all records in a table in one call. It can also return a forward-only cursor for paginating through tables containing more than tens of thousands of records. |
| getRecordsFromCursor |
This action is the fastest way to paginate through records, tail the last N records, repeatedly read the same N records, skip records, and fetch records forward or backward. Both skip and fetch can move forward or backward in any combination, such as skipping ahead and fetching backward. Some actions create forward-only cursors. |
| getRecordsInKeyRange |
This action is the fastest way to retrieve a bounded set of records in index order. Use this action to treat a table as a hierarchical-key-value store. Use |
| getRecordsStartingAtKey |
This action is the fastest way to start at a specific key and walk records in index order. It is typically used to look up records that are near a key. It can also retrieve records before and after a key value. |
| getRecordsUsingSQL |
This action is the fastest way to join tables, run complex filters, sort data using unindexed fields, and run analytic queries. |
Data Change Stream (DCS)
These actions manage connections and streams.
| Action | Description |
|---|---|
| alterStreamingConnection | Alters connection settings to a FairCom DB or RTG server. |
| createAndStartDataChangeStreams | Initialize one or more data change streams. |
| createStreamingConnection | Creates a connection to a FairCom DB or RTG server. |
| deleteDataChangeStreams | Deletes specified data change streams. |
| 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. |
| describeDataChangeStreams | View information about specified data change streams. |
| listDataChangeStreams | Return a list of data change streams that match all specified filters. |
| 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. |