Data Structures

How things are organized and represented in our API

Views, Tables, and Forms

In our API we use the concept of a view to reference data in TrackVia. A view is a way of looking at a data in a table, but views can have filters and can hide certain fields. This is how we enforce read permissions in TrackVia. By not referencing the table directly users of various permission levels can see data in the same table through a view that prevents them from accessing information that is sensitive.

Similarly we use the idea of a form to enforce write permission. Forms can hide or show certain fields from the user in accordance with their permission level.

The user that you authenticate as when using the API will have access to the views and forms as defined by their role in the application. Super users and application admins will have access to everything, while limited users will only be able to read and write to the tables and fields they have access to in their views and forms.

For more on the difference between tables and views see our knowledge base.

Data Types

Single Line, Email, and Link

All single line, email, and link fields are represented as strings of length 255 characters or less. The only difference between them being that email and link fields will make sure that the values passed in to them are valid email addresses or URLs.

Paragraph

All paragraph fields are represented as strings of length 65,536 characters or less.

Number, Percentage, Currency, Auto Counter

Number, percentage, currency, and auto counters are represented as doubles in our API.

Drop Down

Drop downs are represented by strings of 255 characters or less. To unselect a drop down pass in null.

Checkboxes

Checkboxes are represtened by lists of strings of 255 characters or less. To unselect all checkbox choices pass in null.

Date and Date Time

Both date and date time data types are represented by strings formatted as strings. For input we try to support as many different time formats as possible, but we prefer ISO-8601 format to ensure date and time are always parsed correctly. Note, if the timezone is not specified we will parse times using the timezone of the user. For output we use the ISO-8601 format yyyy-MM-dd'T'HH:mm:ssZ.

TrackVia Users

TrackVia users are represented by their unique numeric ID. To find the numeric ID of a user use our /openapi/users end point.

Relationships

Parent child relationships are represented by the unique numeric ID of the parent record stored in the child record. The relationship name is used to reference the relationship. For example, if table Manufacturers has a parent-child relationship with table cars, where each car has a manufacturer, and this relationship is called "car manufacturer" then each car's record will have a field called "car manufacturer" where the value is the numeric ID of a manufacturer.

Document and Image

Documents and images are stored as binary files. These fields use the special file end points /openapi/views/{viewId}/records/{recordId}/files/{fieldName}

Calculated fields

Calculated fields will be represented as the data type that they calculate to. So, a calculated number will be represented as a double and so forth. You will not be able to write to a calculated field.