Introduction to the Windows Live Contacts API

  • Article

Windows Live Contacts maintains an address book for users that contains names, addresses, telephone numbers, and e-mail addresses for their contacts. If users with Windows Live Contacts address books wanted to ship goods from your site to their contacts, it would be very convenient to be able to grant you permission to use their current address books, and to pick out the correct shipping information for your site to use. It would be even more convenient if your site double-checked the address book entry immediately prior to shipment of a back-ordered item, so that if the addressee had moved in the intervening period you could detect the address change in the user's address book and notify them about the problem before shipping.

The API for the Windows Live Contacts Address Book service uses HTTP GET, POST, PUT, and DELETE requests to find, insert, update, and remove Address Book objects, which are specified by URIs. This document will briefly discuss how a Web site can use the Windows Live Contacts API, through the Windows Live Data service, to utilize a user's centralized Address Book.

We assume that the reader is a Web developer who is familiar with HTML and with the HTTP protocol, and that the reader can understand C#.

Prerequisites

Before using the Windows Live Contacts API through the Windows Live Data service, your site must first obtain permission to use the desired resource from Windows Live Data, in the form of an owner handle, which is used to construct all request URIs. This is described in Windows Live Data Authentication Tasks.

Before the site can successfully complete a request to the Windows Live Contacts API through the Windows Live Data service, the site must be able to authenticate to Windows Live Data, using one of the three possible authentication mechanisms: Domain Authentication, Mutual SSL Authentication, and RPS (Relying Party Suite) Authentication. These are described in Introduction to Windows Live Data Authentication.

Windows Live Contacts API Overview

The Windows Live Contacts API has four "verbs," corresponding to four HTTP request methods:

  • GET retrieves whatever information is identified by the Request-URI; the response body includes the data fragments that were retrieved as XML. Equivalent to FIND.
  • POST inserts the XML data that is enclosed in the request body as a child of the element(s) identified by the Request-URI. When successful, the response code will be 201 (Created) and contain a Location header that points to the newly created object(s). Equivalent to INSERT.
  • PUT updates the object that is identified by the Request-URI with the XML data that is supplied in the request body. When successful, the response code will be 204. No content is returned. Equivalent to UPDATE.
  • DELETE removes the data object that is identified by the Request-URI. When successful, the response code will be 204. No content is returned.

Examples of each of these are given later in this topic in the Using HTTP Methods section.

The Windows Live Contacts Request-URI follows the following format.

https://cumulus.services.live.com/[owner handle]/LiveContacts...

Windows Live Contacts will return an XML document in its own XML schema, of which the top level is <LiveContacts>. The URI constructed beyond LiveContacts corresponds to the XML path to the desired part of the address book. For example, a GET request to the bare path

.../LiveContacts

is a request for the entire address book belonging to the owner handle. The path

.../LiveContacts/Contacts

asks for all contacts in the address book, but no owner information or tags. The path

.../LiveContacts/Contacts/Contact(1345223)/Emails/Email(52343)

asks for a specific e-mail address (ID 52343) from a specific contact (ID 1345223) in the address book.

For example, an ASP.NET site written in C# could issue a request for the whole address book, where the string variable uri contains the desired destination URI:

https://cumulus.services.live.com/wlddemo@hotmail.com/LiveContacts

The string variable token contains the saved Domain Authorization Token value. The C# code might look something like this:

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);
request.Method = "GET";
request.Headers.Add("Authorization", 
"DomainAuthToken at=\"" + token + "\"");
try {
   HttpWebResponse response = (HttpWebResponse)request.GetResponse();
   //request succeeded, process response
   ... 
} catch (WebException ex){
   //request failed, handle error
   ... 
}

Address Book Schema Overview

The overall structure of the Windows Live Contacts schema is the following.

<LiveContacts> 
   <Owner> 
      <FirstName/>
      <LastName/>
      <WindowsLiveID/>                  
   </Owner>                        
      <Contacts> 
         <Contact> 
            <ID>{ContactID}</ID> 
            <WindowsLiveID>{Passport Member Name}</WindowsLiveID> 
            <Comment>comment here</Comment> 
            <Profiles/> 
            <Emails/> 
            <Phones/> 
            <Locations/> 
         </Contact>
      </Contacts>
</LiveContacts>

Using HTTP Methods

As we discussed in the API Overview section, the Windows Live Contacts API has four "verbs" corresponding to four HTTP request methods: GET, POST, PUT, and DELETE.

As we have already discussed, GET retrieves all data, including child elements and containers, at the level specified in the URI.

POST is used for inserting values under the URI specified. So, for example, if the user had filled in the e-mail information for one of his or her contacts, for which you already know the ID from retrieving the information, and the user then wanted your site to add that data to his or her Windows Live Contacts on his or her behalf, you could issue a POST request to

.../LiveContacts/Contacts/Contact(<Contact ID>)/Emails

with a body of

<Email> 
   <EmailType>Personal<EmailType>
   <IsDefault>true</IsDefault> 
   <Address>blah@example.com</Address>
</Email>

PUT is used to update existing values at the level of the URI specified. So, for example, if the user wanted to correct the spelling of his or her first name, you could update the Windows Live Contacts on his or her behalf by issuing a PUT request to

.../LiveContacts/Owner

with a body of

<owner>
   <FirstName>Krzysztof</FirstName>
</owner>

PUT uses merge, not replace, semantics so it can be used to update multiple existing values. For example, if a user wanted to change both the EMailType and Address of the previous Email without altering the IsDefault value they could do so by by sending a PUT request to

.../LiveContacts/Contacts/Contact(<Contact ID>)/Emails/Email(<Email ID>)

With a body of

<Email>
   <EmailType>Business</EmailType>
   <Address>fuzz@example.com</Address>
</Email>

Finally, PUT requests that contain empty elements can be used to clear out fields.

DELETE is used to remove a single child from a collection. So, for example, if the user wanted to remove the contact with ID 12345 from his or her address book, you could delete it from Windows Live Contacts on his or her behalf by issuing a DELETE request to

.../LiveContacts/Contacts/Contact(12345)

Additional information about using the Windows Live Contacts API can be found in the Windows Live Contacts API Reference.