Welcome, guest Sign In

Synchronizing the Address Book

The synchronize method retrieves Address Book changes and updates the master Address Book.

Synchronization is performed by exchanging a sequence of change events between the Address Book and the application. Synchronization from the Yahoo! Address Book is a read-only operation, and can only be performed by applications to whom the user granted read access. Synchronization to the Yahoo! Address Book is a read-write operation, and can only be performed by applications to whom the user granted write access. The following table contains the entities that represent the change events.

Table 2.8. Synchronization Events

Event Meaning
address-book-reset Resets the Address Book. Only valid in events from the Address Book.
add-contact Adds a new contact to the Address Book.
remove-contact Removes a contact from the Address Book.
add-category Adds a new category to the Address Book. Only valid in events to the Yahoo! Address Book.
rename-category Renames a category in the Address Book. Only valid in events to the Yahoo! Address Book.
remove-category Removes a category from the Address Book. Only valid in events to the Yahoo! Address Book.

Typically, the calling application will maintain a cached copy of the Address Book that is synchronized with the master copy. The revision (rev) of the updated Address Book is kept with the cached copy as an opaque numeric value. The revision of the Address Book is an opaque number that refers to a particular state of the Address Book. It is passed to the Address Book in subsequent Requests for cache validation. For both read and write requests, the revision of the cached copy is specified in the URL parameter myrev. If the remote application does not have a cached copy, it should specify myrev=0. Both the read and the write operations provide the caller with the list of changes since the specified revision and with the new revision of the Address Book. The server response to using a value for the myrev URL parameter that does not come from a previous response is unspecified.

Note

Updates sent to the Yahoo! Address Book are field-level updates and category-level updates, whereas events received from the Yahoo! Address Book are contact level updates and the response contains the full current list of categories

Synchronize Request

The format of the from read-only synchronize Request is:

The format of the to read-write synchronize Request is:

The synchronize Request will contain a section for each event type to be synchronized. The general format for each section of a synchronize Request contains the following header:

Contact ID, Field ID and Category ID
IDs in Requests

When updating a contact, the request must include the correct contact ID cid (or contact temporary ID ctempid for updating contacts added previously inside the same request).

When updating a field, the request must contain the correct field ID fid (or field temporary ID ftempid for updating fields added previously inside the same request) and the correct ID (temporary ID) of the contact that the field belongs to.

When removing a contact, the correct contact ID cid (or temporary ID) must be specified.

When removing a field, the correct field ID fid (or temporary ID) must to be specified, along with the correct ID (temporary ID) of the contact that the field belongs to.

When removing a category, the correct category ID (catid) or the category name must to be specified.

When adding a contact, no ID is needed. When adding a field, the correct ID (temporary ID) of the contact that the field should belong to must be specified.

IDs in Responses

Responses from the Address Book will include the ID for added and updated contacts, the ID for each field that currently exists in added or updated contacts, and the ID of all categories that currently exist in the address book.

Temporary IDs

Temporary IDs were introduced for advanced users of the API to facilitate batch synchronization from a source that can send multiple separate updates to the same contact or field in one synchronization session. Temporary IDs are the mechanism that allows advanced users to off-load the combining of those updates to Yahoo! Address Book servers.

In Requests containing an add-contact event, you may specify a unique temporary contact ID using the ctempid property. ctempid can be used later in the same request to refer to the contact in place of the Contact's cid, which is not known until after the Contact has been added. It is possible to send update-contact events that refer to a newly added Contact without knowing its ID.

In Requests containing an add-contact event or an update-contact event, field add operations such as add-name or add-phone may specify a unique temporary field ID using the ftempid property. ftempid can be used to refer to the field in place of the Field's fid, which is not known until after the Field has been added. It is possible to send field update and removal operations that refer to a newly added Field without knowing its ID.

Responses that refer to a Contact that was tagged with a ctempid in the Request will contain the same ctempid contact property in the Response. This gives the caller an additional way to match contact add requests with the resulting diffs.

Responses that refer to a Field that was tagged with a ftempid in the Request will contain the same ftempid field property in the Response. This gives the caller a way to pair field add requests with the resulting diffs. (As opposed to Contacts, for Fields the temporary ID is the only way to pair a field in the Request with a field in the Response.)

Table 2.9. Synchronization Request IDs

Event Type ID
add-contact ctempid (optional)
update-contact cid (or ctempid)
remove-contact cid (or ctempid)
add-field ftempid (optional)
update-field fid (or ftempid)
remove-field fid (or ftempid)
add-category new category name
rename-category catid or old category name, and new category name
remove-category catid or category name
add-to-category catid or category name
remove-from-category catid or category name


Table 2.10. Synchronization Response IDs

Event Type ID
add-contact cid (and ctempid when known)
update-contact cid (and ctempid when known)
remove-contact cid (and ctempid when known)
fields (examples: name, email) fid (and ftempid when known)
category catid and category name

ADD-CONTACT

The add-contact event block adds a new contact to the user's Address Book, or it merges the new contact with an existing contact in the user's Address Book.

The section Temporary IDs above explains in more detail the purpose of the optional ctempid property.

Add Contact Response Conditions

The Response to an add-contact event can be threefold:

  1. Contact was not valid
  2. Contact was added without duplication
  3. Contact was merged with an existing contact
Contact was not valid

The Response will be an error entity containing additional information about why the add operation failed. See Error Reporting for more information.

Contact was added without duplication

The Response returns a new Contact ID (cid) within a success entity and add-action set to add. Success responses are small blocks with optional contact ID (cid) or category ID (catid), and an optional add/merge indicator (add-action).

Contact was merged with an existing contact

The Response returns the Contact ID (cid) of the contact with which the new contact was merged within a success entity and add-action will be merge.

Comparing the add-contact event and the addContacts method

The mode of operation of the add-contact event in the synchronize method is very similar to the mode of operation of the addContacts method.

Both mechanisms allow you to add contacts without creating duplicates in the user's Address Book.

The difference between these two mechanisms is limited to the format of the request and the format of the response.

  1. The Request of an add-contact event used with the synchronize method contains a series of updates in the form of field additions, such as add-name, add-phone, and category membership updates, such as add-to-category. In contrast, an addContact method Request contains contacts in the form of fields, such as name and phone, and category membership information within category tags.
  2. A success Response from the add-contact event used with the synchronize method is a success entity, with properties cid and add-action. In contrast, a success Response from the addContact method is a contact entity with properties cid and add-action containing details of the added/merged contact. The synchronize method contact details are contained in the diffs output part of the response.
UPDATE-CONTACT

Use the update-contact event block to update the fields of a Contact specified by its cid(Contact ID) or by its ctempid (temporary Contact ID). Responses from the Address Book include the cid for added and updated contacts. The list of event blocks for each field to be added, updated or removed can be any of the following:

Table 2.11. Update-Contact Event Blocks

Event Block  
ADD-(field) Adds a new field to the Contact. Provide field data. Examples: ADD-NAME, ADD-YAHOOID
UPDATE-(field) Updates a contacts field. Reference the field with the field ID (fid). Supply the updated data. Examples: UPDATE-NAME, UPDATE-YAHOOID
REMOVE-FIELD Removes the field specified by the field ID (fid).
ADD-TO-CATEGORY Adds the Contact to the specified category.
REMOVE-FROM-CATEGORY Removes the Contact from the specified category.

Note

When updating a structured field, such as a name or an address, you need to specify all components of the field together in the update. Components that you want to clear need to be specified with an empty value.

The following example XML Synchronization Request adds two contacts to the user's Address Book and immediately updates the second contact. This example shows the use of Temporary IDs.

Note

If you do not need to update contacts and fields in the same Request that adds them, refer to existing contacts by cid and to existing fields by fid instead of using Temporary IDs.

The following JSON Synchronization Request contains several events: add-contact, remove-contact, add-category, rename-category, add-to-category, and remove-category.

The following JSON synchronization Request adds a new contact.

The Response, as follows, includes the confirmation and two change events, the second of which was caused by the Request itself.

REMOVE-CONTACT

Use the remove-contact event block to remove a Contact from the user's Address Book. Specify the Contact with either the cid or ctempid:

The Response to a remove-contact is property-less entity of type success:

ADD-CATEGORY

Use the add-category event block to add a new category by name to the Address Book:

The Response to an add-category event returns a new category ID (catid) within a success entity. Success responses are small blocks that contain the category ID:

RENAME-CATEGORY

Use the rename-category event block to rename a category in the user's Address Book. Specify the category ID (catid) or the current category name and supply the new category name.

The Response to a rename-contact is property-less entity of type success.

REMOVE-CATEGORY

Use the remove-category event block to remove a category from the user's Address Book. Supply either the name or ID (catid) of the category to remove.

The Response to a remove-category is property-less entity of type success.

Synchronize Response

A synchronize Request returns a Response with either an error or a success block. The general format of a Response is as follows:

Note

The table of categories at the beginning of the response may be omitted by Address Book servers for performance reasons if there are no events to report. When present in the response, the table of categories is the complete list of categories that currently exist in the Address Book.

An add-contact operation causes cid and add-action to be set in the corresponding success response entity. An add-category operation causes catid to be set in the corresponding success response entity. Other operations produce an empty success entity on success at the corresponding position.

Error entities are standard error responses relating to the particular operation. See the Error Reporting section for more information.

Success responses are small blocks with an optional add action indicator (add or merge), a contact ID, or a category ID:

Interaction Diagrams

Let's consider the following scenario: A Yahoo! Address Book user starts using a new application that caches the Address Book. The first Request from the application retrieves the whole Address Book. The first check for changes is negative. However, a later check for changes propagates a recent change to the application. In the last step, the application carries out an update to the Address Book and, at the same time, it retrieves changes that allow it to bring its cached copy back up to date.

Example (JSON)

The most interesting exchange from the above scenario is the last request, where the application submits an update and at the same time it retrieves updates.

The Request follows:

Here is the Response, which includes the confirmation and two change events, the second of which was caused by the Request itself:

Example (XML)

In this example the application submits an update and at the same time retrieves updates. This example is identical to the previous example, except that it uses XML instead of JSON.

The Request follows:

Here is the Response, which includes the confirmation and two change events, the second of which was caused by the request itself:

Table of Contents

Copyright © 2009 Yahoo! Inc. All rights reserved. Copyright | Privacy Policy

Help us continue to improve the Yahoo! Developer Network: Send Your Suggestions