Selecting Entities

There are several methods to select entities, or data within the entity using the Capture API. These are the building blocks of user management. Select the methods which most fit your needs.

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

• Record Selectors – These are parameters that can be used with API calls to select a single entity.
• entity_path – This is an optional parameter that can be used to return a plural in a entity, instead of the entire entity.
• attribute_name – This is an optional parameter that is used to target an attribute in a entity, and not the entire record.
• created and lastUpdated – Two optional parameters that may be used as built in checks to make sure the entity wasn’t recently updated, or deleted and recreated.

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:

• id — This parameter refers to the id attribute required in every entity.
• uuid — This parameter refers to the uuid attribute required in every entity.
• Both the key_attribute and key_value parameters — the path to any unique attribute in the schema, and key_value is the value of that attribute used to select the record. The attribute may be inside a plural as long as it has a “unique” constraint.

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:

• entity
• entity.update
• entity.replace
• entity.delete

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:

• entity
• entity.count
• entity.find
• entity.update
• entity.replace
• entity.delete

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:

• entity
• entity.update
• entity.replace
• entity.delete

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:

• entity
• entity.find

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.

Capture checks the created and lastUpdated arguments against the entity that you are attempting to update or delete. When present, Capture checks these arguments 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:

• entity
• entity.update
• entity.replace
• entity.delete