Selecting Data

Selecting Entities

The following concepts are provided to help you further understand how the the RESTful API can be used:

Each of these are explained in greater detail in their respective sections below:

Record Selectors

These are for API calls that operate on a single record (entity, entity.update, entity.replace, and entity.delete). Each call requires one of the following parameters to select an individual record:

Example: selecting a record using id=1 is the same as using key_attribute=id and key_value=1.

Note: When specifying a unique string, quotes are required.

Record selector parameters may be used with these calls:

Example

Consider an entity type user with a “unique” constraint on the name attribute, and populated with the following records:

[
{ "id" : 1,
"uuid" : "12345678-1234-1234-1234-123456789123",
"created" : "2011-12-19 21:18:40.416558",
"lastUpdated" : "2012-02-08 22:45:41.743699",
"name" : "John",
"friends" : [ { "id" : 2, "name" : "Bob" },
{ "id" : 3, "name" : "Jane" }
]

},
{ "id" : 4
"uuid" : "12345678-1234-1234-1234-123456789123",
"created" : "2011-12-14 21:50:20.318456",
"lastUpdated" : "2012-02-06 04:00:16.648444",
"name" : "Jeff",
"friends" : []
}
]

Then all of the following sets of arguments are equivalent:
id=1 & attribute_name=/friends#2
key_attribute=name & key_value=John & attribute_name=/friends#2
key_attribute=/friends/name & key_value=Bob & attribute_name=/friends#2
entity_path=/friends & id = 2
entity_path=/friends & key_attribute = name & key_value = Bob<

Each of the cases above will select the following entity:
{ "id" : 2, "name" : "Bob" }

entity_path

The entity_path argument is the path to a plural in the schema. This argument causes the API call to be applied to the plural as though that plural were an entity type. You can use it to retrieve or update elements in a plural without specifying the parent record.

This can be used with:

attribute_name

This argument is a value path (see Attribute Paths) to any attribute in a specific record. Select the record with a record selector (id, uuid, or key_attribute and key_value) and optionally an entity_path, then use the attribute_name to select that part of the record to retrieve or update.

The attribute_name may be used with:

attributes

This is a JSON array of attribute paths. If provided, then only those attributes will be returned in the result. Otherwise, all attributes are returned. This argument is relative to the attribute selected by entity_path and attribute_name.

This may be used with:

created and lastUpdated

When updating or deleting a record, you can use these arguments to check that a record has not been updated since a previous known timestamp, or that the record has not been deleted and recreated. This feature effectively allows you to serialize updates correctly.

Registration checks the created and lastUpdated arguments against the entity that you are attempting to update or delete. These arguments are checked against either or both of the created or lastUpdated attributes in the record. If an attribute does not match its respective argument, then the call does not update the record and will yield an error.

These may be used with: