FairCom Edge APIs

FairCom Edge's API documentation for software developers, equipment manufacturers, and automation engineers

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.

Important

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.

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.

Inputs

These actions are part of the JSON Hub API, which is available in FairCom Edge. This section provides several actions to 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 are part of the JSON DB API. This section provides actions to 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"`	`"alterOutput"` configures an existing integration.
`"createOutput"`	`"createOutput"` creates and new integration.
`"deleteOutput"`	`"deleteOutput"` removes a previously created integration.
`"describeOutputs"`	`"describeOutputs"` returns all available information about each specified output.
`"listOutputs"`	`"listOutputs"` obtains a list of the names of previously created outputs.

Integration tables

This section provides actions to create, alter, delete, describe, and list integration tables. These actions are available in FairCom Edge and FairCom MQ.

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
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

Transform processes

This section provides several actions to create, alter, delete, describe, list, and run transform processes. These actions are part of the JSON Hub API and are available in FairCom Edge and FairCom MQ.

Action	Description
`"alterTransform"`	`"alterTransform"` renames and edits the properties of an existing transform process.
`"createTransform"`	`"createTransform"` creates a transform and saves it by name for reuse in MQTT topics and inputs.
`"deleteTransform"`	`"deleteTransform"` deletes one or more transforms and returns a complete description of each deleted transform so that the transform can be recreated easily.
`"describeTransforms"`	`"describeTransforms"` returns all available information about each specified transform.
`"listTransforms"`	`"listTransforms"` obtains a list of the names of existing transforms.
`"runTransform"`	`"runTransform"` runs a transform and returns the transformed data.

MQTT Topics

This section provides several actions to configure, delete, describe, and list MQTT topics. These actions are part of the JSON MQ API and are available in FairCom Edge and FairCom MQ.

Action	Description
`"configureTopic"`	`"configureTopic"` configures a topic and its many settings. You can change a topic to use a different integration table and control how MQTT data is transformed before inserting it into the integration table. You can also forward MQTT messages to other MQTT topics.
`"deleteTopic"`	`"deleteTopic"` deletes an MQTT topic.
`"describeTopics"`	`"describeTopics"` returns all available information about specified MQTT topics.
`"listTopics"`	`"listTopics"` lists the names of MQTT topics that the server is tracking.

Broker connections

The JSON Hub API: broker connection actions are part of the JSON MQ API. This section provides actions to configure, delete, describe, and list broker connections.

Action	Description
`"configureBrokerConnection"`	`"configureBrokerConnection"` creates or updates a reusable connection to an external broker, which may be another instance of FairCom MQ, FairCom Edge, or an MQTT broker from another vendor.
`"deleteBrokerConnection"`	`"deleteBrokerConnection"` deletes a previously created broker connection.
`"describeBrokerConnections"`	`"describeBrokerConnections"` returns information about specified broker connections.
`"listBrokerConnections"`	`"listBrokerConnections"` lists all available broker connections that have been created.

Databases

These actions are part of the JSON DB API. This section provides actions to 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 are part of the JSON DB API. This section provides actions to 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 are part of the JSON DB API. This section provides actions to 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 are part of the JSON DB API. This section provides actions to 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 are part of the JSON DB API. This section provides actions to 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	`"getRecordsByIds"` directly returns records from a database using their primary key, which can be one or more fields. This action treats a table as a simple key-value store when the primary key is the `"id"` field. Use `"getRecordsFromCursor"` to treat a table as a hierarchical-key-value store. This action is the fastest way to retrieve records by ID or a multi-field primary key.
getRecordsByIndex	`"getRecordsByIndex"` typically returns a cursor that quickly retrieves records in index order. The server can optionally filter records using a SQL-like filter expression before returning them. The cursor can efficiently paginate through thousands of records at a time. The cursor can fetch records forward and backward and skip records in both directions. 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	`"getRecordsByPartialKeyRange"` retrieves records from a database table that match a partial key in the specified index. The server can optionally filter records using a SQL-like filter expression before returning them. 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	`"getRecordsByTable"` quickly retrieves records from a database table in table order. The server can optionally filter records using a SQL-like filter expression before returning them. 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	`"getRecordsFromCursor"` retrieves records from a cursor returned from another `"getRecords..."` action. A cursor can efficiently retrieve thousands of records at a time. 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	`"getRecordsInKeyRange"` retrieves records from a database table within an index's specified range of keys. The specified index may contain multiple fields. The server matches index keys against partial or complete values. The upper or lower bounds of the key range can be set or omitted. The server can filter records using a SQL-like filter expression before returning them. 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 `"getRecordsByIds"` to treat a table as a simple key-value store.
getRecordsStartingAtKey	`"getRecordsStartingAtKey"` retrieves records from a database table starting with the record that most closely matches the specified key in the selected index. 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	`"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 records. This action is the fastest way to join tables, run complex filters, sort data using unindexed fields, and run analytic queries.

Quality of Service