Syncing Contacts

This feature of the Contacts API enables a client to synchronize a local copy of contact data with the data stored in the Yahoo Address Book servers. Examples of clients are laptops, mobile devices, and smart phones. The syncing calls do not support contact filtering, bucketing, or pagination.

Scenarios for Contact Syncing

The following scenarios illustrate syncing between client applications and Yahoo Address Book. As you read the scenarios, note the revision numbers passed back and forth during the syncing requests and responses.

For readability, the scenarios use the terms "Client" and "Address Book Server." "Client" refers to a client application running on a local device such as a laptop or smart phone. A Yahoo user can run client applications on different devices, each storing a local copy of that user's address book data. The term "Address Book Server" is shorthand for the RESTful Web service (Contacts API) that accesses the Yahoo Address Book data stored on Yahoo servers.

Initializing a Client

This scenario shows how a client gets all of the contact data when it needs to initialize its local copy of the data.

  1. On a laptop, the user runs an address book application for the first time. This application is Client A.
  2. Client A makes a GET sync request with rev=0.
  3. The Address Book Server returns the current state of the contact data to Client A.
  4. Client A initializes its local copy of the contact data, which is now ready for use.
Syncing Multiple Clients

The following scenario shows how two different clients can modify local contact data and then sync with the Yahoo Address Book on the server. Client A adds a contact named Joe Smith. Client B deletes a contact named Fred Jones. These clients represent different applications used by the same owner of the Yahoo Address Book data.

  1. On the Address Book Server, the current rev is 98.
  2. Client A, an application running on a home PC, makes a GET sync call. Client A processes the response and updates its local contact data to rev 98.
  3. On Client A, the user adds a contact named Joe Smith. At this time, a sync request is not made.
  4. The user then switches to Client B, which is running on a phone. The user asks Client B to sync contacts. Client B makes a GET sync call, processes the response, and updates its local contact data to rev 98.
  5. Client A makes a PUT sync call to add the user Joe Smith. In this call, Client A specifies rev=98.
  6. The Address Book Server accepts the request, adds Joe Smith, increments the rev to 99, and sends a response to Client A. Because there are no other updates needed by Client A, the diff in the response is empty.
  7. Client A processes the response and changes its rev to 99.
  8. On Client B, the user deletes the contact Fred Jones.
  9. The user asks Client B to sync the contacts. Client B makes a PUT sync call, with rev=98, sending the operation to delete Fred Jones.
  10. The Address Book Server deletes Fred Jones and increments its rev to 100. The server returns the response, which indicates a success for deleting Fred Jones. The response also includes a diff to add Joe Smith.
  11. Client B adds Joe Smith to its local copy and updates its rev to 100.
  12. Client A makes a GET sync call, specifying rev=99.
  13. The Address Book Server sends the response to Client A. The response includes the operation to delete Fred Jones and the latest rev of 100.
  14. Client A deletes Fred Jones and updates its rev to 100.
Merging Contacts

In this scenario, two different clients add a contact with the same name. However, the two entries are different: Client A includes the email address and Client B specifies the phone number. The clients represent different applications, run by the same user to access the same data on the Address Book Server.

  1. On the Address Book Server, the current rev is 98.
  2. Client A, an application running on a home PC, makes a GET sync call. Client A processes the response and updates its local contact data to rev 98.
  3. On Client A, the user adds a contact named Joe Smith, specifying the email address for this contact. At this time, a sync request is not made.
  4. The user then switches to Client B, an application running on a smart phone. The user asks Client B to sync contacts. Client B makes a GET sync call, processes the response, and updates its local contact data to rev 98.
  5. Client A makes a PUT sync call to add the user Joe Smith. In this call, Client A specifies rev=98.
  6. The Address Book Server accepts the request, adds Joe Smith, increments the rev to 99, and sends a response to Client A. Because there are no other updates needed by Client A, the diff in the response is empty.
  7. Client A processes the response and changes its rev to 99.
  8. On Client B, the user adds the contact Joe Smith, specifying the phone number. Note that in an earlier step, Client A added a contact with the same name, but with the contact's email address.
  9. The user asks Client B to sync the contacts. Client B makes a PUT sync call, with rev=98, sending the operation to add Joe Smith.
  10. The Address Book Server server updates the phone number for Joe Smith and then increments its rev to 100. The server returns the response Client B. The response indicates a success for adding Joe Smith with the phone number, specifies that this contact was merged with an existing one, and includes a diff for rev 98. The diff describes that changes needed to sync rev 98 with rev 100.
  11. Client B adds Joe Smith (with both email and phone) to its local copy and updates its rev to 100.
  12. Client A makes a GET sync call, specifying rev=99.
  13. The Address Book Server sends the response to Client A. The response includes the operation to add John Smith and the latest rev of 100.
  14. Client A updates the phone number for Fred Jones and updates its rev to 100.

Elements of the ContactSync Object

The following table describes the JSON or XML data contained in the contactsync element. To view the structure of the data, see the example JSON and XML sections later in this chapter.

GET: Sync From Yahoo Address Book to Client

To pull sync data from Yahoo Address Book to a client, call HTTP GET on the following endpoint:

/v1/user/{guid}/contacts?view=sync&rev={rev-number}

The {guid} identifies the Yahoo user of the address book data. The view=sync parameter value is required. The value of the rev parameter, also required, is the revision number of the contact data that is currently on the client. To get the entire list of contacts, specify the rev=0 query parameter. Do not guess the value of the rev query parameter: Specify either 0 or the value returned in the previous response. In the response body, the rev element is the revision number of the latest contact data on Yahoo Address Book.

The returned data is in the contactsync element within the response body. The data includes an array of categories and an array of Contact Objects. Because category lists are short, the entire category list is returned every time, not just the differences. To update its copy of the categories list, the client replaces the entire list. The contact data returned, as shown in the following examples, includes the most current complete Contact Objects, not just the fields of the Contact Objects that have changed since the last revision. Also, the contact data includes sync operations such as add, update, and remove. If no sync is required, that is, if the client's data is already up to date, the contactsync element returned is empty.

Example JSON Response for GET Contactsync
Example XML Response for GET Contactsync

PUT: Sync From Client to Yahoo Address Book

To push sync data from the client to Yahoo Address Book, call the HTTP PUT operation on the following endpoint:

/v1/user/{guid}/contacts

For this PUT operation, do not specify the view=sync or rev query parameters with the URI. The sync data from the client, including the revision number (rev), is in the contactsync element within the request body. In the request body, the value of rev is the revision number of the client's current contact data. In the response body, rev corresponds to the latest contact data on Yahoo Address Book.

Example JSON Request Body for PUT Contactsync
Example XML Request Body for PUT Contactsync
Example JSON Response for PUT Syncresult
Example XML Response for PUT Syncresult

Table of Contents