The API operates with various items that consist of associations and/or fields with certain properties. This article describes the properties in more detail.

Name

The name of a field represents property name of a JSON object, while the name of an association defines class of the corresponding JSON object (which can be an item or a collection of items).

Type

This property describes the kind of an association or the format of a field's value.

Association Types

There are just two types of associations:

  • Item: a single item (a JSON object) associated with the current item. For example, a status associated with a job.
  • Collection: a set of items (an array of JSON objects) associated with the current item. For example, a list of jobs associated with a user.

Field Types

Currently the following field types are supported by the API:

  • Boolean: a boolean value, e.g. true or false.
  • Date-Time: a ISO 8601 timestamp, e.g. 2014-01-30T23:31:57+00:00.
  • Float: a positive or negative number with a fractional or decimal component, e.g. 2.9515.
  • Integer: a positive or negative number without a fractional or decimal component, e.g. 730.
  • String: a line of text in UTF-8 encoding, e.g. sample text.

Value Restrictions

The main restriction that applies to the value of a field or an association is obviously its type. But apart from that the API may impose other restrictions depending on the system restrictions, role permissions, account settings and actual values of other fields.

In most cases the set of restrictions will be generated automatically by the API, but in other cases some predefined restrictions may apply.

Access

Some fields and associations restrict read/write access to their corresponding values. Also, it is not always possible to manipulate them by applying request modifiers (e.g. sort or filter by value).

The API supports the following access types:

  • Read: get the actual value of a field or association.
  • Write: set a new value for a field or association.
  • Change: change current value of a field or association.
  • Sort: apply the sort modifier to re-arrange items in a collection by the value of the corresponding field or association.
  • Filter: apply the where modifier to get only items that satisfy the criteria set in the modifier.

Visible by Default

This property determines whether the corresponding field or association will be included into the response object by default. Visibility can be controlled via the fields modifier.

Required

This property determines whether it is required to provide a value for a field or association when making a non-GET request.

In some cases a value may be required to be provided only on certain request types, while in other cases actual values and/or existence of other fields or associations will affect whether the value for the field or association in question has to be provided.