Retrieving and Editing Entities

Retrieving an Entity

To retrieve an entity from the API, use one of the get* methods listed in the API method index. These methods take an entity ID and (optionally) a rev identifier. (See the Revs and ETags documentation for additional information about revs and caching.)

Expected Response

The response for any get* method is typically a dictionary representation of the requested entity. For a detailed description of exactly which fields may be returned for each entity, see the corresponding Nut_Api_Render_Model documentation from the API response index.

For example, the array returned by getLead is documented in Nut_Api_Render_Model_Lead.

If an entity is not returned, the response will be an error message or a notice that your currently cached entity is still valid.

Editing an Entity

To edit an entity, use one of the edit* methods listed in the API method index. These methods take an entity ID, a rev identifier, and an array containing new/updated values for the entity.

The rev identifier is mandatory for the edit* methods. See "Revs", below, for an overview of how revs are used in editing an entity.

Expected Responses

The response for any edit* method is typically a dictionary representation of the updated entity. (See "Expected Responses" for retrieving an entity, above.)

If an entity is not returned, the response will be an error message or a notice that you cannot edit the entity because your currently cached entity is invalid. (See "Revs", below, for an overview of how revs are used in editing an entity.)

Multi-Value Fields

Many entities have fields which can contain more than one value. For example, a Contact may have multiple addresses and phone numbers; and a Lead may have multiple Contacts.

Each of these fields, if present in a response, will include one value called --primary. This will be a duplicate of another value in the multi-value field; it represents the primary value (for example, a Contact's primary phone number).

Editing Multi-Value Fields

When you wish to add a value (for example, an additional phone number) to one of these multi-value fields, you must also include all preexisting values in that field. The edit* methods replace all existing values with whatever value(s) you supply in your API call.

This behavior allows you to delete values from multi-value fields using the edit* family of methods.

If a multi-value field is not included in the "changes" array you pass to the edit method, the preexisting values are not affected.

This behavior does not apply to fields that can only contain a single value (such as a Contact's name).

Revs

Revs are Nutshell's approach to application-level cache control. The Nutshell API issues a revision identifier (rev key) as part of its response each time you retrieve an entity.

When you call an edit* method, you must include the rev you have cached for the entity you intend to edit. If the entity has been changed on the server since you last retrieved it, the API will not let you make your changes. This prevents the possibility of accidental data loss.

For additional information on revs, see the Revs and ETags documentation.