Protocol Record

Overview

Record Identifier Format

The record identifier is a string composed of a record type (string) and a record name (string), joined together with a slash character (/). This notation is called a canonical record identifier.

Examples are book/code_complete and student/john_doe.

Both the record type and record name must be consists of alphanumeric characters and underscores. Underscore must not appear in the begining of record type and record name.

The record name can be a user-friendly string or a randomly generated string used to identify a record in the database. A record identifier uniquely identifies a record. It is the responsibility of the client to guarantee the uniqueness of record identifiers.

It is recommended to generate a GUID for record name, although this is not a requirement.

Record Object Format

The record object refers to data and metadata about the record in transit between the server and the client. The record object format does not represent how the record is saved in the database storage layer.

Record object consists of a dictionary of key value pairs. This data structure is similar to dict or hash data structures in many programming languages.

Developer may define keys to save application data in a record. Such key must not begin with an underscore character (_) as these keys are reserved by the system to save record metadata. System reserved keys should not be exposed to the developer the same way as if they mixed with application-defined keys.

System reserved keys

• _id (string, required)

  The record identifier used to uniquely identify a record in the scope of the database. This identifier is required when creating, fetching, modifying and deleting individual records.

  Record identifier cannot be changed after record creation.

• _type (string, required)

  Note: This field was formerly used to denote record type. This is since be repurposed.

  Denotes whether the data contained in the record object is an actual record or an error object. Currently these are the only available types.

• _revision (string, optional)

  Opaque string generated by the system to track changes of the record. This helps detect if change has occurs in a record as the revision of a record is updated every time the record is modified.

  When returning data to the client, the system always returns the revision string which the client should save together with application-defined keys. When client create or modify a record, the client may omit the revision key. See action-specific documentation for details.

• _created_at (datetime, optional)

• _created_by (string, optional)

• _updated_at (datetime, optional)

• _updated_by (string, optional)

• _code (string, when returning error)

  The error code identifying the error that has occurred.

Format in transit

When in transit, the application defined keys are mixed with system reserved keys. Here is an JSON-formatted student record object as an example:

{
    "_id": "student/susan_boyle",
    "_type": "record",
    "_revision": "LtpkLZY8OUzka",
    "name": "Susan Boyle",
    "gender": "female",
    "interests": ["signing"]
}

Returning error

When an error occurred while carrying out an action that only affects a subset of record, an error object related to each such record is returned in the response.

The format of an error object is the same as that of an error payload (See Request), plus the following fields:

• _type (string, required)

  Must be error, indicating that this object is an error object instead of a record object.

• _id (string, required)

  The record identifier for which the error is related to. The error has occurred when carrying out the specified action targeting this record.

  For example, if the record of a record identifier cannot be found, the record identifier will be specified in this field.

Here is an example of a fetch that results in an error:

{
    "_id": "student/susan_doyle",
    "_type": "error",
    "message": "Record `student/susan_doyle` cannot be found.",
    "type": "FetchRecordsRequestError",
    "code": 100,
    "info": {
        "id": "student/susan_doyle"
    }
}

record:fetch

Overview

Returns structured records from a database by specifying record identifiers.

Records to be fetched may have different types.

You can limit the data returned for each record by specifying the desired_keys with data keys that the client needs for that request. If a record does not have data of the specified key, the key will be missing from the returned result.

The records will be returned in the result key as an array of records. The order of the records may not follow that specified in the ids parameter. If a record cannot be fetched, an error object will be returned instead of record data.

Parameters

• access_token (string, required)

• database_id (string, required)

  The database identifier of the database in which records are stored and to be fetched from.

• ids (array of string, required)

  Identifiers of the records to be fetched from the database.

• desired_keys (array of string, optional)

  A subset of keys to be fetched from each record instead of all keys of the records.

Returns

• database_id (string) supplied database identifier

• result (array of objects)

  Returns each record object identified in the ids field. For each record that was unable to be fetched, error object will be returned stating the failure for each record.

Example

curl -X POST -H "Content-Type: application/json" \
  -d @- https://example.com/api/v1 <<EOF
{
    "action": "record:fetch",
    "access_token": "ACCESS_TOKEN",
    "ids": ["student/1001", "student/1002"],
    "desired_keys": ["name", "gender"]
}
EOF

{
    "request_id": "REQUEST_ID",
    "database_id": "DATABASE_ID",
    "result": [
        {
            "_id": "student/1001",
            "_type": "record",
            "_revision": "CpzrfppXcpBN",
            "name": "Mary",
            "gender": "female"
        },
        {
            "_id": "student/1001",
            "_type": "error",
            "message": "Record `student/1001` cannot be found.",
            "type": "FetchRecordsRequestError",
            "code": 100,
            "info": { }
        }
    ]
}

record:save

Overview

Create or modify records in the database.

The client calls this action in order to make changes to existing records in the database or create new one if such record does not exist. This depends on whether the record ID supplied already exists in the database: if record with the record ID already exists, the record is modified rather than created. When creating a new record, all the keys specified in the record object will be saved to the new record.

When modifying an existing record, all the keys specified in the record object will cause the corresponding keys in the existing record updated. Keys not specified will not be changed in the record in the database.

Parameters

• access_token (string, required)

• database_id (string, required)

• records (array of objects, required)

  New records to be saved to the database, or existing records to be modified.

  If _revision key is specified in record object, the system will only modify an existing record if the existing record has a revision that matches the specified value.

Returns

• database_id (string) supplied database identifier

• result (array of objects)

  If the record is successfully created or modified, the record object will be returned with only system-reserved keys (record metadata). Otherwise, an error is included here.

Example

curl -X POST -H "Content-Type: application/json" \
  -d @- https://example.com/api/v1 <<EOF
{
    "action": "record:save",
    "access_token": "ACCESS_TOKEN",
    "database_id": "DATABASE_ID",
    "records": [
        {
            "_id": "student/1004",
            "_type": "record",
            "name": "John",
            "gender": "male"
        },
        {
            "_id": "student/1005",
            "_type": "record",
            "_revision": "SeO6DY7A7TyP"
            "name": "Peter",
            "gender": "male"
        }
    ]
}
EOF

{
    "request_id": "REQUEST_ID",
    "database_id": "DATABASE_ID",
    "result": [
        {
            "_id": "student/1004",
            "_type": "record",
            "_revision": "irK8IXC2LdMq"
        },
        {
            "_id": "student/1005",
            "_type": "error",
            "message": "Record `student/1005` cannot be found.",
            "type": "SaveRecordsRequestError",
            "code": 100,
            "info": { }
        }
    ]
}

record:delete

Overview

Delete records in the current database.

The client calls this action to remove a record from the current database. If this action was completed successfully, the record will cease to be available.

Parameters

• access_token (string, required)

• database_id (string, required)

  Database identifier.

• ids (array of string, required)

  Record identifiers of which the records are to be deleted from the database.

Returns

• result (array of object, required)

  For each record that cannot be deleted, an error is included here. An empty array means all requested records are deleted successfully.

Example

curl -X POST -H "Content-Type: application/json" \
  -d @- https://example.com/api/v1 <<EOF
{
    "action": "record:delete",
    "access_token": "ACCESS_TOKEN",
    "database_id": "DATABASE_ID",
    "ids": ["student/1004", "student/1005"]
}
EOF

{
    "request_id": "REQUEST_ID",
    "database_id": "DATABASE_ID",
    "result": [
        {
            "_id": "student/1005",
            "_type": "error",
            "message": "Record `student/1005` cannot be found.",
            "type": "SaveRecordsRequestError",
            "code": 100,
            "info": { }
        }
    ]
}

record:query

Overview

Returns records that matches certain criteria specified by client.

The client calls this action when it wants to fetch a subset of records of certain record type. The client do this by specifying a criteria that the record data meets. For example, student records maybe fetched by matching student name instead of student record ID.

Parameters

• access_token (string, required)

• database_id (string, required)

  The database identifier of the database in which records are stored and to be fetched from.

When making fresh queries:

• record_type (string, required)

  The record type to find matches for. The returned records will be limited to this record type.

• predicate (string or query object, required)

  (TBD) The query language that specifies the matching criteria.

• limit (integer, optional)

  The maximum number of records to be returned. This limit maybe further limited by configuration at the server.

• desired_keys (array of string, optional)

  A subset of keys to be fetched from each record instead of all keys of the records.

• sort (array of sort descriptors, optional)

  An array of sort descriptors defining how the returned records are to be sorted.

• eager (array of key paths, optional)

  A set of key paths of which referenced records will be returned together in the response. For each matching record, all referenced objects will be returned in the eager_result key.

  Note: Currently, eager loading only support traversing single key path. In other words, only the first key path will be considered and that key path must not contains ..

When paging through a query:

• cursor (string, required)

  Server generated record cursor to fetch the next batch of records.

Returns

• result (array of objects)

  The list of record objects that matches the specified criteria.

• eager_result (array of objects)

  The list of record objects that are referenced by records matching the specified criteria. Only those that are specified with the eager parameter will be returned.

• cursor (string)

  Opaque string generated by the server to fetch the next batch of records when submitted in subsequent calls to this action.

Example

curl -X POST -H "Content-Type: application/json" \
  -d @- https://example.com/api/v1 <<EOF
{
    "action": "record:query",
    "access_token": "ACCESS_TOKEN",
    "database_id": "DATABASE_ID",
    "record_type": "student",
    "predicate":
        ["and",
            ["eq", {"$type": "keypath", "$val": "name"}, "Peter"],
            ["eq", {"$type": "keypath", "$val": "city.name"}, "Hong Kong"]
        ],
    "limit": 10,
    "sort":
        [
            [{"$type": "keypath", "$val": "name"}, "asc"]
        ],
    "eager":
        [
            {"$type": "keypath", "$val": "city"}
        ]
}
EOF

{
    "request_id": "REQUEST_ID",
    "database_id": "DATABASE_ID",
    "result": [
        {
            "_id": "student/1001",
            "_type": "record",
            "name": "Peter",
            "city": {"$type": "ref", "$id": "hongkong", "$class": "city"}
        },
        {
            "_id": "student/1002",
            "_type": "record",
            "name": "Peter",
            "city": {"$type": "ref", "$id": "hongkong", "$class": "city"}
        }
    ],
    "eager_result": [
        {
            "_id": "city/hongkong",
            "_type": "record",
            "name": "Hong Kong"
        },
    ],
    "cursor": "CURSOR_ID"
}