Air Forms API Description

If you've chosen to create cloud based tables, you'll will have entered a data source URL telling Air Forms where it should send its requests for data to. This section outlines the API you'll need to implement on your webserver to allow Air Forms to access your database systems.

Air Forms uses a simple API over HTTPS (or HTTP, however this is STRONGLY discouraged). Air Forms uses HTTP POST method to post a JSON payload describing the action your server should take. The server should then reply with a JSON response.

The API consists of eight functions:

authenticate

record_count

records_at_offset

new_record

delete_record

update_record

values_for_list

data_for_media_column

Function Descriptions

authenticate

Verifies that the user has permission to access this database.

Request Parameters

username

Required. A string specifying the users username.

password

Required. An string specifying the users password. This string is not encrypted or hashed, meaning that it can be used to authenticate against external directory services to determine a users access. If the Data Source URL you have specified is NOT secured using SSL, users passwords will be exposed in clear text to other network users. This request should ALWAYS be secured using SSL.

Response Parameters

result_code

Required. A string specifying the outcome of the request. Set to "0" if the user has permission to access.

records_at_offset

Returns the specified maximum number of ordered records for a given search predicate, beginning at a specified offset.

Request Parameters

table

Required. A string specifying the table to fetch records from.

recid

Required. A string specifying the column name of the row identifier. This should be the primary key column name.

offset

Required. A string specifying the offset within the ordered set of records in the table.

max_records

Required. A string specifying maximum number of records to return. You may return fewer records in the response.

columns

Required. An array of column names to fetch from the table.

summary_columns

Required. An array of summary column objects to fetch from the table.

search_predicate

Optional. An array specifying the column name and value pairs from which to build the search query. See the Entities section for information on the format of this array. Used to return correct record counts.

Response Parameters

result_code

Required. A string specifying the outcome of the request. Set to "0" on successful request.

records

Required. An ordered array of column name value pair dictionaries for every record returned. Media column values return a "Media Value Description" entity encoded as a string, which does not contain actual file data.

new_record

Required. A string specifying the column name of the row identifier. This should be the primary key column name.

defaults

Optional. An array of column name and value pairs used to populate the new record.

search_predicate

Optional. An array specifying the column name and value pairs from which to build the search query. See the Entities section for information on the format of this array. Used to return correct record counts.

Response Parameters

result_code

Required. A string specifying the outcome of the request. Set to "0" on successful request.

recid_value

Required. A string specifying the value of the newly created record unique row identifier. This should be the value of the primary key column of the new record.

record_count

Required. A string specifying the number of records in the table, given the search predicate supplied.

total_record_count

Required. A string specifying the number of records in the table, ignoring the search predicate supplied.

delete_record

Required. A string specifying the column name of the row identifier. This should be the primary key column name.

recid_value

Required. A string specifying the value of the unique row identifier column of the record to delete.

search_predicate

Optional. An array specifying the column name and value pairs from which to build the search query. See the Entities section for information on the format of this array. Used to return correct record counts.

Response Parameters

result_code

Required. A string specifying the outcome of the request. Set to "0" on successful request.

record_count

Required. A string specifying the number of records in the table, given the search predicate supplied.

total_record_count

Required. A string specifying the number of records in the table, ignoring the search predicate supplied.

update_record

Required. A string specifying the column name of the row identifier. This should be the table's primary key column name.

recid_value

Required. A string specifying the value of the unique row identifier column of the record to update.

column_type

Required. A string specifying the type of data which is stored in this column. (Text, Number, Media etc)

column

Required. A string specifying the column name to update.

value

Required. A string specifying the value to set the column to. If column_type is set to 'Media' this value is set to a 'Media Value' entity encoded as a string.

search_predicate

Optional. An array specifying the column name and value pairs from which to build the search query. See the Entities section for information on the format of this array. Used to return correct record counts.

autoupdate

Optional. An array specifying columns which require autoupdating based on this column value being changed. See the Entities section for information on the format of this array.

Response Parameters

result_code

Required. A string specifying the outcome of the request. Set to "0" on successful request.

record_count

Required. A string specifying the number of records in the table, given the search predicate supplied.

total_record_count

Required. A string specifying the number of records in the table, ignoring the search predicate supplied.

The Media Value Description entity is a dictionary of objects describing a media value, but without its associated file data. This entity is returned with the records_at_offset function to minimise data transfer. It gives Air Forms enough information about the value to manage caching of media column data on the device. Air Forms uses the file_md5 to determine whether the cached file on device is valid, if it's not, the data_for_media_column function is called as necessary.

The Relationship entity is an object which represents a relationship between two tables.

id

Required.

name

Required.

table_1

Required.

table_2

Required.

criteria

Required. An array of relationship criteria entities defining the conditions of the relationship.

The Relationship Criteria entity.

table_1_column

Required.

table_2_column

Required.

comparison_operator

Required.

Important Security Considerations

This API should ALWAYS be implemented over SSL secured HTTP connections. Username and password strings are transmitted unobscured in the request payloads. If you are considering implementing this API over HTTP instead of HTTPS, you will be exposing usernames and passwords to the world.