Windows Live REST Explorer – Messenger Connect

Roadmap

This post is part of a series of related posts on how to use Windows Live Messenger Connect.

1. (this post) Using Messenger Connect REST Explorer for exploring Windows Live resources.

2. Using the Messenger Connect JavaScript API for listing your contacts.

3. Getting contacts in three different ways (API and REST).
4. Messenger Connect - Initializing Controls

Overview

Messenger Connect is a new offering from Microsoft that allows you (a developer of a web site) to allow your customers to log into your web site using Windows Live credentials. Your Messenger Connect -enabled web site furthermore, allows users, once they have authenticated and consented, to be able to access their social graph (contacts, activities, etc.) while on your site. For more information see this Windows Live post. It is similar to FaceBook Connect which was discussed previously in this blog here and here. However, Messenger Connect comes to the table with a more mature set of APIs (Windows Live SDK - download here) and more flexibility for different scenarios. In this post we'll deal with the first step in understanding Messenger Connect and that is understanding the data model (technically called the Resource Model) that supports these capabilities. We'll do this using a tool that Windows Live has provided called Windows Live REST Explorer (REX): http://rex.mslivelabs.com/. We will view data from and write data to the Windows Live cloud.

Viewing Resource Data

The Windows Live Resource Model is similar to the Facebook API, but whereas the Facebook API had some public data you could access without having an Application ID (i.e. registering with Facebook). Instead, viewing Windows Live resources using REX requires you to log in to begin seeing any data. Furthermore, with REX you are exploring your own data, not the data of others.

The Windows Live Resource Model defines top level resources such as contacts, profiles, and activities, collections of data entries, and data entries (an individual contact or profile, e.g.). It's not completely intuitive at first glance, but suffice it to say you can get to all of your Windows Live data one way or another. Each top level resource, collection, and entity has a unique URI address. The Windows Live Resource Model is RESTful in that you make requests (via the browser client) and receive responses. Each request is for a specific (REST) resource that is uniquely addressed. So, every piece of your Windows Live data is accessible with a well formed URI and can be accessed provided you have been authenticated.

REX is an interface to explore your Windows Live resources, but it is not how you will typically consume this data from the cloud. Rather, you will likely use the APIs provided by in the Messenger Connect release, like the JavaScript API or the .NET API. For this post we'll concentrate on just the REST explorer, REX, to understand the resources and how they are organized and then in a follow up post deal with accessing resources using APIs.

Let's look closely at REX. The first thing you have to do is choose a Scope and then log in. The idea of a scope is that it indicates what resources you want to access and what you want to do with them (view, update, e.g.). Let's make sure the scope matches the screenshot below. In particular we want to select the ability to update contacts (WL_Activities.Update). WL = Windows Live. Activities = resource. Update = permission desired.



After setting the scopes click the Connect button and you should receive the consent dialog shown below.



If you click the "What will I share?" link you can review what is going to be shared. It will match the scopes you specified. The real interesting scenario for reviewing what you will share is for a web site that is Messenger Connect-enabled and you, now playing the part of the user, do not know what scopes have been specified and you want to review them before consenting. It’s your chance to refuse sharing your data. But in this scenario here, you are just viewing your own data so you should be okay to consent.



After successfully authenticating and providing consent you are at the top level of your resource tree. REX allows you to see resource data in a variety of formats (RSS, ATOM, JSON, or POX). Change it a few times to see the different formats, but for this post we’ll stick with JSON.



In all the screenshots in this post the CID is obscured. When you log in your CID will be unique to your Windows Live credentials.

From the REX home page you'll be able to drill down through data going from top level resources to resource collections to data entities. So, for example, if you click through the ContactsLink on the home page you come to the collection page of categories and contacts.



Clicking the AllContactsLink, you come to the contacts collection page.



Clicking through to any of the SelfLinks of a contact brings you to a contact entity page. You've drilled all the way down to a resource, a contact in this case.



Don't forget that if you log into http://home.live.com/ with the same credentials you used for REX you will access the same data, but through the UI. Also, if you captured the URL http://sn1.apis.live.net/V4.1/cid-**YOUR-CID-HERE**/Contacts/AllContacts, closed the browser, reopened and pasted it in the address bar you will receive either nothing or an error The idea is that you can’t access a collection or entity without first authenticating.

Modifying Resource Data
You can also use REX to make changes to your data. Doing it through REX is not the preferred way but it helps you understand the REST commands that are in use behind the JavaScript Library is part of this release. So let's suppose we want to add a new activity using the Windows Live REST Explorer. Note that in REX there is a "Request" tab and a drop down for the action (verb) you want to take (GET, PUT, POST, DELETE, HEAD, OPTIONS). So far we've been just using the "Response" tab and GET requests. To create a new activity we'll use a POST action and fill in the Request tab with the appropriate information. This is all documented fairly well in the MSDN topic REST API Service and Resource Model. Our goal is to make this appear in our Messenger social feed (http://home.live.com):

1. Start at the collection page of MyActivities: http://bay.apis.live.net/V4.1/cid-***YOUR-CID-HERE***/MyActivities
2. Select POST from the action dropdown
   Click the Request tab and enter data similar to the following to create a new activity marking a favorite:
   

    
   {"__type": "MarkFavoriteActivity:http://schemas.microsoft.com/ado/2007/08/dataservices",
   "ActivityVerb": "http://activitystrea.ms/schema/1.0/favorite",
   "ApplicationLink": "http://www.travelmarx.net",
   "ActivityObjects": [ 
      {
           "ActivityObjectType": "http://activitystrea.ms/schema/1.0/*",
           "AlternateLink": "http://travelmarx.blogspot.com",
           "PreviewLink": "http://travelmarx.blogspot.com/thumbnail.jpg",
           "Title": "A blog I follow.",
           "Summary": "About traveling - without moving."
      }
     ]
   }
   

   
   
3. Note that we have kept the default data presentation of JSON and so we'll enter data in this way as well. For more information on the syntax see http://json.org/.
4. Click the submit button (the green arrow) and the activity should be created and appear in your Messenger Social feed as shown above.
   

So, there you have it, a quick overview of the Windows Live REST Explorer (REX) that allows you to browse Windows Live resource data.