Migrating your Live Connect v4.1 app to v5.0

Article
04/16/2012

Migrating your app

One of the key design principles in developing Live Connect, Version 5.0 was ensuring a relatively painless migration from Windows Live Messenger Connect, Version 4.1. This of course includes functional parity in terms of supported operations but also ensuring that user consent granted to your app is not lost during the upgrade process.

In this document, we will talk about how to move your Windows Live Messenger Connect v 4.1 apps to Live Connect v5.0.

Supported operations in Live Connect v5.0

In Live Connect v5.0, there is functional parity in the operations supported when compared to Messenger Connect, v 4.1. A number of new operations have also been added. Here is a list of all the supported operations in v5.0 when compared to v4.1.

If your app uses a v4.1 scope that you want to maintain user consent for when migrating, see the “Mapping between v4.1 and v5.0 offers” section later in this guide for details.

Identity (profiles)

The following table describes the new operations available when compared to v4.1.

Operation

User’s profile info

User’s profile image

User’s birthday

User’s email addresses

User’s postal addresses

User’s phone numbers

Hotmail

The following table describes the new operations available when compared to v4.1.

Operation	In v4.1?	In v5.0?
User’s contacts	Yes	Yes
User’s friends	Yes	Yes
User’s calendars	Yes (partial)	Yes
User’s calendar events	Yes (partial)	Yes
Subscribe to external calendars	No	Yes

SkyDrive

The following table describes the new operations available when compared to v4.1.

Operation	In v4.1?	In v5.0?
User’s root folder	No	Yes
User’s folders	Yes	Yes
User’s albums	Yes	Yes
User’s storage quota	No	Yes
User’s single folder	Yes	Yes
User’s single album	Yes	Yes
User’s single file	Yes	Yes
User’s single photo	Yes	Yes
User’s photo tags	No	Yes
User’s photo comments	No	Yes

Messenger

The following table describes the new operations available when compared to v4.1.

Operation	In v4.1?	In v5.0?
User’s status	Yes	Yes
User’s activities	Yes	No

How to modify settings for your 4.1 app?

If you have an existing app, you can reuse that app’s client ID for your Live Connect v5.0 app. If you want to modify some of the app’s settings, you can do this at the Live Connect app management site. You can also visit the app management site for creating a new app.

Referencing the APIs in v5.0

The Live Connect APIs include implementations for JavaScript, managed languages like C#, iOS, Android, and Representational State Transfer (REST). You can download the latest version of the Live SDK by visiting the download section in the Live Connect Developer Center.

Referencing the APIs with JavaScript

Client-side websites and scripts that use JavaScript

To reference the APIs, for client-side websites and scripts that use JavaScript, set a reference to a web-based version of the wl.js file from your code, like this.

A web-based debugging version of wl.js, called wl.debug.js, is also available. It is an uncompressed version of wl.js. To call it, substitute wl.debug.js for wl.js, like this.

Web-based localized versions of the APIs are available for JavaScript. You add a URL segment that specifies the culture for the localized version that you want to use. For example, to load the web-based Japanese version, your app uses a URL like this.

For a complete list of supported localized versions, see Supported locales.

Referencing the APIs with REST

Use the info in Server-side scenarios to learn about available REST calls and their syntax. To learn how to make REST calls for your specific platform and programming language combination, see your documentation.

Moving to OAuth 2.0

Differences between OAuth WRAP and OAuth 2.0

Messenger Connect v4.1 uses a protocol called OAuth WRAP to get user consent for the data that your app needs. Live Connect v5.0 uses an evolved version of OAuth WRAP, OAuth 2.0. There are many similarities between the two protocols and a few differences as well.

To learn more about OAuth WRAP, see the Messenger Connect OAuth WRAP reference page.

To learn more about OAuth 2.0, see the Live Connect OAuth 2.0 reference page.

Reusing your Messenger Connect v4.1 refresh token

If your app requested and obtained a refresh token from Messenger Connect v4.1 with the OAuth WRAP authorization code flow, this refresh token can be reused in the Live Connect v5.0 OAuth 2.0 flows. This is beneficial as it allows your app to migrate to Live Connect v5.0 without your users needing to reauthenticate. In the case where a refresh token has expired, you would need to get consent from your user. You can easily detect this by checking for an error on the call. If you do get an exception, we recommend you use the equivalent Wave 5 scopes listed here.

In Messenger Connect v4.1, a refresh token was used to get a new access token by making a POST request with the refresh token to consent.live.com by sending the following request.

Messenger Connect v4.1 refresh token request

POST /RefreshToken.aspx Host: consent.live.com wrap_refresh_token={refresh_token}

Using a refresh token in Live Connect v5.0 to get a new access token looks very similar, although there are some additional request parameters required.

Live Connect v5.0 refresh token request

POST /oauth20_token.srf Host: login.live.com Content-Type: application/x-www-form-urlencoded client_id={RT}&redirect_uri={REDIRECT_URI}&client_secret={CLIENT_SECRET}&refresh_token={REFRESH_TOKEN}&grant_type=refresh_token

The Messenger Connect v4.1 response contains just the access token to be used by your app. Note that the scope is not provided in the request to the token endpoint. This is required in order for your application to reuse consent from v4.1.

Messenger Connect v4.1 refresh token response

wrap_access_token="{access_token}"&wrap_access_token_expires_in={expiration}

The Live Connect v5.0 response looks as follows. Note that Live Connect v5.0 returns a new refresh token, which your app must remember in place of the refresh token it used for the original request. Also note that the format of the response is in JavaScript Object Notation (JSON) as compared to the query string format used in v4.1.

Live Connect v5.0 refresh token response

{ "access_token": "{access_token}", "expires_in": {expires_in}, "refresh_token": "{refresh_token}", "scope": "{original scope passed}", "token_type": "bearer" }

Mapping between v4.1 and v5.0 offers

In order to reuse the user consent acquired by your app obtained in v4.1, all requests must omit the scope parameter. If you are creating a new app or need the user to re-consent, please use these scopes. The following table provides the mapping between the scopes your app may have used in v4.1 and the functional equivalents in v5.0.

v4.1	v5.0
WL_Profile.View	wl.basic wl.emails
WL_Profile.ViewFull	wl.basic wl.emails wl.birthday
WL_Profile.UpdateStatus	wl.share
WL_Contacts.View	wl.basic wl.contacts_birthday
WL_Activities. View	wl.basic
WL_Activities.Update	wl.share
WL_Photos.View	wl.photos
WL_Applications.Create	wl.applications_create

Moving to the v5.0 API

In order to interact with the REST API, the app must make the appropriate HTTP call to the following URL.

{HTTP Method} https://apis.live.net/v5.0/{PATH}?access_token={access_token}

Where:

{HTTP Method} – the appropriate HTTP method: GET(read), PUT(update), POST(create), DELETE(delete), MOVE(move), or COPY(copy)

{PATH} – the path for the particular resource

{access_token} – See the “” section

Calling an operation

In order to call an operation, you must know this info.

The path you want to call. See the “Supported operations in Live Connect v5.0” section earlier in this guide for details.
The HTTP method that must be used. See the “Supported operations in Live Connect v5.0” section earlier in this guide for details.
A valid access token.
The type of request body to construct for a POST or PUT call. See the REST Reference for details.

The libraries have built in functionality to support the different type of HTTP calls as well as ensure that the access token specified is valid at all times. In addition to these, the libraries also have support for downloading and uploading a file (although currently this is not supported for JavaScript for the web).

In v5.0, we offer a convenient, powerful, and elegant way to interact with the Live Connect REST API. The WL.api method accesses data by a property, which contains a JSON-formatted object that defines the values of the method.

Below is an example of how you can use the library to get a user’s profile info. Calls can be made to retrieve different user data by simply replacing the path and the HTTP method as needed.

JavaScript

For more information on the API model for the various libraries, see the Live Connect API .

Mapping operations between v4.1 and v5.0 operations

In v4.1, an app was able to do this.

Get a user’s contacts.
Get a user’s profile info and profile pictures.
Get info about a user’s folders, albums, files, and photos.
Share a user’s status.

A v5.0 app can do these operations and take advantage of the other operations that are made available in v5.0. See the “Supported operations in Live Connect v5.0” section earlier in this guide.

However, there is a change on how these operations are called in v5.0. The following sections will walk through the semantics of making these calls.

Get a user’s contacts

In order to get a user’s contact list, the app must get consent from the user. If your v4.1 app already has the WL_Contacts.View scopes, then reconsent is not required, and the consent will be carried forward.

In v4.1, contacts were loaded by doing this.

JavaScript request

REST request

GET https://apis.live.net/v4.1/cid-CID/contacts/AllContacts

In v5.0, we have made loading contacts simpler by adding this friendlier syntax.

Contacts

The following code snippet shows how to get a user’s contact info using the v5.0 REST API.

JavaScript request

function readContact_onClick() { WL.api({ path: "me/contacts", method: "GET" }).then( function (response) { parseResult(response) }, function (responseFailed) { document.getElementById("infoArea").innerText = "Error calling API."; } ); }

REST request

GET https://apis.live.net/v5.0/me/contacts?access_token={access_token}

JSON response

{ "data": [ { "id": "contact.e7fd4a29000000000000000000000000", "first_name": "William", "last_name": "Flash", "name": "William Flash", "gender": null, "is_friend": false, "is_favorite": false, "user_id": null, "email_hashes": [], "updated_time": "2011-09-22T17:33:09+0000" } ] }

For other supported operations for contacts, See Hotmail (contacts). For other supported operations for contacts, See Hotmail (contacts).

Get a user’s profile info and profile image

To get a user’s profile info and profile picture, the app must get consent from the user. If your v4.1 app already has the WL_Profile.View scopes, then reconsent is not required, and the consent will be carried forward.

In v4.1, profiles were loaded by doing this.

JavaScript

function loadAllProfiles() { dataContext.loadAll(Microsoft.Live.DataType.profiles, profilesLoaded); } function profilesLoaded(dataLoadCompletedEventArgs) { profileCollection = dataLoadCompletedEventArgs.get_data(); Sys.Debug.trace("Profiles are loaded."); }

REST request

GET https://apis.live.net/v4.1/cid-CID/Profiles/

In v5.0, we have made loading profiles simpler by adding this friendlier syntax.

Profile info

The following code snippet shows how to get a user’s profile info using the v5.0 REST API.

JavaScript request

function profile_onClick() { WL.api({ path: "me ", method: "GET" }.then( function (response) { parseResult(response) }, function (responseFailed) { document.getElementById("infoArea").innerText = "Error calling API."; } )); }

REST request

GET https://apis.live.net/v5.0/me?access_token={access_token}

JSON response

{ "id": "9d24497f7fef8f33", "name": "William Flash", "first_name": "William", "last_name": "Flash", "link": "https://profile.live.com/cid-9d24497f7fef8f33/", "birth_day": 1, "birth_month": 4, "birth_year": null, "gender": "male", "emails": { "preferred": "willamf@hotmail.com", "account": "willamf@hotmail.com", "personal": "williamf@hotmail.com", "business": null }, "locale": "en_US", "updated_time": "2012-01-10T03:22:09+0000" }

Profile image in v5.0

JavaScript request

function profilePicture_onClick() { WL.api({ path: "me/picture", method: "GET" }).then( function (response) { parseResult(response) }, function (responseFailed) { document.getElementById("infoArea").innerText = "Error calling API."; } ); }

REST request

GET https://apis.live.net/v5.0/me/picture?access_token={access_token}

JSON response

{ "location": "https://blufiles.storage.msn.com/....." }

For other supported operations for a user’s profile, see Identity (Profiles).

User’s folders, albums, files, and photos

To get info about a user’s photos, the app must get consent from the user. If your v4.1 app already has the WL_Photos.View scope, then reconsent is not required for reading photos and the consent will be carried forward.

In v4.1, photos were loaded by doing this.

JavaScript

function loadAllPhotos() { dataContext.loadAll(Microsoft.Live.DataType.photos, profilesLoaded); } function profilesLoaded(dataLoadCompletedEventArgs) { profileCollection = dataLoadCompletedEventArgs.get_data(); Sys.Debug.trace("Profiles are loaded."); }

REST request

GET https://apis.live.net/v4.1/cid-CID/Photos/

In v5.0, we have made loading albums and photos simpler by adding this friendlier syntax.

Reading album properties

The following code snippet shows how to get a user’s album info using the v5.0 REST API.

JavaScript request

REST request

GET

https://apis.live.net/v5.0/album.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125?access_token={access_token}

JSON response

{ "name": "Wallpapers", "description": null, "parent_id": "folder.9d24497f7fef8f33", "upload_location": "https://apis.live.net/v5.0/folder.9d24497f7fef8f33.9D24497F7FEF8F33!165/files/", "count": 0, "link": "https://skydrive.live.com/redir.aspx?cid=9d24497f7fef8f33&page=view&resid=9D24497F7FEF8F33!165&parid=9D24497F7FEF8F33!161", "type": "album", "shared_with": { "access": "Just me" }, "created_time": "2008-03-17T08:02:39+0000", "updated_time": "2008-03-17T08:02:39+0000" }

In v5.0, we made it easier to get info about a user’s SkyDrive files and folders.

Reading folder properties

The following code snippet shows how to get a user’s folder info using the v5.0 REST API.

JavaScript request

REST request

GET

https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125?access_token={access_token}

JSON response

{ "name": "Videos", "description": null, "parent_id": "folder.9d24497f7fef8f33", "upload_location": "https://apis.live.net/v5.0/folder.9d24497f7fef8f33.9D24497F7FEF8F33!165/files/", "count": 0, "link": "https://skydrive.live.com/redir.aspx?cid=9d24497f7fef8f33&page=view&resid=9D24497F7FEF8F33!165&parid=9D24497F7FEF8F33!161", "type": "folder", "shared_with": { "access": "Just me" }, "created_time": "2008-03-17T08:02:39+0000", "updated_time": "2008-03-17T08:02:39+0000" }

Reading file and photo properties

The following code snippet shows how to get a user’s file and photo info using the v5.0 REST API.

JavaScript request

REST request

GET

https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!125?access_token={access_token}

JSON response

{ "name": "2208120743_7c41fa4524_o.jpg", "description": null, "parent_id": "folder.9d24497f7fef8f33.9D24497F7FEF8F33!265", "size": 397298, "comments_count": 0, "comments_enabled": true, "tags_count": 0, "tags_enabled": true, "picture": "https://storage.live.com/....s1p0p7c41fa4524_o.jpg", "source": "https://storage.live.com/...._o.jpg", "upload_location": "https://apis.live.net/v5.0/file.9d24497f7fef8f33.9D24497F7FEF8F33!293/content/", }

Update status

To update a user’s status, the app must get consent from the user. If your v4.0 app already has the WL_Activities.Update scope, then reconsent is not required, and the consent will be carried forward.

The following code snippet shows how to set a user’s status using v4.1.

JavaScript request

dataContext.loadAll(Microsoft.Live.DataType.Activities, nil, activitiesLoadded); } function activiiessLoaded(dataLoadCompletedEventArgs) { … activitiesCollection = dataLoadCompletedEventArgs.get_data(); … } } activitiesCollection.add(newActivity); activitiesCollection.save(saveCompleted);

REST request

POST https://apis.live.net/v4.1/cid-CID/Activities Authorization: Bearer ACCESS_TOKEN Content-Type: application/json { ……." }

In v5.0, you do this.

JavaScript request

WL.api({ path: "me/share", method: "POST", body: { message: "Hello, Windows Live!" } }).then(function(response){ //status updated. });

REST request

POST https://apis.live.net/v5.0/me/share Authorization: Bearer ACCESS_TOKEN Content-Type: application/json { message: "Explore Windows Live", link: "https://explore.live.com/home", description: "Stay in touch and share your world: email, photos, movies, video chat, and more!", picture: "https://explore.live.com/a1ce...part of URL omitted for brevity...481c.jpg", name: "Windows Live Home" }

JSON response

{ "status": "Hello, Windows Live!" }

Migrating your Live Connect v4.1 app to v5.0

Migrating your app

Supported operations in Live Connect v5.0

How to modify settings for your 4.1 app?

Referencing the APIs in v5.0

Moving to OAuth 2.0

Moving to the v5.0 API

Get a user’s profile info and profile image

User’s folders, albums, files, and photos

Update status

Additional resources