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:

GET http://address.yahooapis.com/v1/synchronize
   ?format=format
   &myrev=REV

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

POST http://address.yahooapis.com/v1/synchronize
   ?format=format
   &myrev=REV

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:

+----------------------------------------+
|SYNC-REQUEST                            |
| - events (1..*):                       |
| ... sequence of entities of type:      |
|       * ADD-CONTACT                    |
|       * UPDATE-CONTACT                 |
|       * REMOVE-CONTACT                 |
|       * ADD-CATEGORY                   |
|       * RENAME-CATEGORY                |
|       * REMOVE-CATEGORY                |
+----------------------------------------+

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.

+--------------------------------+
|ADD-CONTACT                     |
| - ctempid (optional)           |
| - fields:                      |
|    +------------------------+  |
|    |ADD-(field)             |  |
|    | ... field contents ... |  |   _
|    | - categories:          |  |    \
|    |    +----------------+  |  |     | when adding fields
|    |    |ADD-TO-CATEGORY |  |  |     | to categories,
|    |    | - data: ...    |  |  |     | either the name
|    |    | (or)           |  |  |     | or the category ID
|    |    | - catid: ...   |  |  |     | is required
|    |    +----------------+  |  |   _/
|    +------------------------+  |
|    .... more field events ...  |   _
| - categories:                  |    \
|    +------------------------+  |     | when adding contacts
|    |ADD-TO-CATEGORY         |  |     | to categories,
|    | - data: ...cat name... |  |     | either the name
|    | (or)                   |  |     | or the category ID
|    | - catid: ...cat id...  |  |     | is required
|    +------------------------+  |   _/
|    .... more memb. events ...  |
+--------------------------------+

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:

Contact was not valid
Contact was added without duplication
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).

+--------------------------------+
|SUCCESS                         |
| - add-action: "add"            |
| - cid                          |
+--------------------------------+

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.

+--------------------------------+
|SUCCESS                         |
| - add-action: "merge"          |
| - cid                          |
+--------------------------------+

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.

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.
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.

+--------------------------------+
|UPDATE-CONTACT                  |
| - cid: ... contact ID ...      |
| (or)                           |
| - ctempid                      |
| - fields:                      |    _
|    +------------------------+  |     \
|    |ADD-(field)             |  |      | optional, repeatable
|    | ... field contents ... |  |      |
|    +------------------------+  |    _/
|    +------------------------+  |     \
|    |UPDATE-(field)          |  |      |
|    | - fid: ... field ID... |  |      |
|    | ... field contents ... |  |      |
|    +------------------------+  |    _/
|    +------------------------+  |     \
|    |REMOVE-FIELD            |  |      |
|    | - fid: ... field ID... |  |      |
|    +------------------------+  |      |
|    .... more field events ...  |    _/
| - categories:                  |     \
|    +------------------------+  |      |
|    |ADD-TO-CATEGORY         |  |      |
|    | - data: ...cat name... |  |      |
|    | (or)                   |  |      |
|    | - catid: ...cat id...  |  |      |
|    +------------------------+  |    _/
|    +------------------------+  |     \
|    |REMOVE-FROM-CATEGORY    |  |      |
|    | - data: ...cat name... |  |      |
|    | (or)                   |  |      |
|    | - catid: ...cat id...  |  |      |
|    +------------------------+  |      |
|    .... more memb. events ...  |    _/
+--------------------------------+

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.

<sync-request>
  <add-contact ctempid="contact1">
    <add-nickname ftempid="nick1">billy</add-nickname>
  </add-contact>

  <add-contact ctempid="contact2">
    <add-name>
      <first>John</first>
      <last>Smith</last>
    </add-name>
    <add-phone home="true" ftempid="phone1">415-111-4165</add-phone>
    <add-nickname ftempid="nick1">Smithy</add-nickname>
    <add-nickname ftempid="nick2">johnny_s</add-nickname>
    <add-address ftempid="addr1">
      <street>1111 Folsom St</street>
    </add-address>
  </add-contact>

  <update-contact ctempid="contact2">
    <update-address ftempid="addr1">
      <street>1111 Folsom St</street>
      <city>San Francisco</city>
    </update-address>
    <update-phone work="true" home="false" ftempid="phone1"/>
    <update-nickname ftempid="nick1">smithy</update-nickname>
    <remove-nickname ftempid="nick2"/>
  </update-contact>
</sync-request>

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

{"type": "sync_request",
 "events": [{"type": "add_contact",
             "fields": [{"first": "David",
                         "middle": "X",
                         "last": "Cohen",
                         "type": "add_name"}],
             "categories": [{"type": "add_to_category", "data": "Directors"}]
            },
            {"type": "remove_contact", "cid": 72},
            {"type": "add_category", "data": "Actors"},
            {"type": "remove_category", "data": "Stars"},
            {"type": "rename_category", "old_category": {"data": "Directors"},
                                        "new_category": {"data": "Producers"}},
            {"type": "add_contact",
             "fields": [{"data": "groening",
                         "type": "add_nickname"}],
             "categories": [{"type": "add_to_category", "data": "Producers"}]
            },
            {"type": "add_contact",
             "fields": [{"first": "Garfield",
                         "type": "add_name"}],
             "categories": [{"type": "add_to_category", "data": "Cats with spaces in their category name are not allowed in"}]
            }
]}

The following JSON synchronization Request adds a new contact.

POST http://address.yahooapis.com/v1/synchronize
   ?format=json
   &myrev=23

{ "type": "sync_request",
  "events": [
    { "type": "add_contact",
      "fields": [
        { "type": "add_name",
          "first": "Jane",
          "last": "Bishop",
        },
        { "type": "add_phone",
          "mobile": true,
          "data": "415-205-9999"
        }
      ],
      "categories": [
        { "type": "add_to_category",
          "data": "Mobile_Friends"
        }
      ]
    }
  ]
}

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

{ "type": "sync_response",
  "lmt": 1168961062,
  "rev": 28,
  "categories": [
    { "type": "category",
      "catid": 7,
      "data":  "Messenger_Buddies"
    },
    { "type": "category",
      "catid": 23,
      "data":  "Family"
    },
    { "type": "category",
      "catid": 599,
      "data":  "Mobile_Friends"
    }
  ],
  "results": [
    { "type": "success",
      "add_action": "add",
      "cid": 543
    }
  ],
  "events" : [
    { "type": "update_contact",
      "cid": 511,
      "fields" : [
        { "type": "name",
          "fid": 512,
          "first": "John",
          "last": "Smith"
        }
      ]
    },
    { "type": "update_contact",
      "cid": 543,
      "fields" : [
        { "type": "name",
          "fid": 600,
          "first": "Jane",
          "last": "Bishop",
        },
        { "type": "phone",
          "fid": 523,
          "mobile": true,
          "data": "415-205-9999"
        },
        { "type": "yahooid",
          "fid": 524,
          "data": "jane.bishop"
        }
      ],
      "categories": [
        { "type": "category",
          "catid": 599
        }
      ]
    }
  ]
}

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:

 +--------------------------------+
 |REMOVE-CONTACT                  |
 | - cid: ... contact ID ...      |
 | (or)                           |
 | - ctempid: ... tag ...         |
 +--------------------------------+

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

+--------------------------------+
|SUCCESS                         |
+--------------------------------+

ADD-CATEGORY

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

+--------------------------------+
|ADD-CATEGORY                    |
| - data: ...cat name...         |
+--------------------------------+

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:

+--------------------------------+
|SUCCESS                         |
| - catid                        |
+--------------------------------+

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.

+--------------------------------+
|RENAME-CATEGORY                 |
| - old-category:                |
|    +------------------------+  |
|    |OLD-CATEGORY            |  |
|    | - data: ...cat name... |  |
|    | (or)                   |  |
|    | - catid: ...cat id...  |  |
|    +------------------------+  |
| - new-category:                |
|    +------------------------+  |
|    |NEW-CATEGORY            |  |
|    | - data: ...cat name... |  |
|    +------------------------+  |
+--------------------------------+

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

+--------------------------------+
|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.

+--------------------------------+
|REMOVE-CATEGORY                 |
| - data: ...cat name...         |
| (or)                           |
| - catid: ...cat id...          |
+--------------------------------+

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

+--------------------------------+
|SUCCESS                         |
+--------------------------------+

Address Book XML/JSON API Developer Guide