REST reference

The Live Connect Representational State Transfer (REST) API enables apps that work with Live Connect to access info programmatically about users, their contacts and friends, their web-based activities and personal status, their media stored on Microsoft SkyDrive, and more.

This topic contains the following sections:

• Supported HTTP verbs
• Support for resumable downloads
• Understanding the objects
• Query parameters
• Structure value options
• Activity object
• Album object
• Application object
• Audio object
• Calendar object
• Comment object
• Contact object
• Error object
• Event object
• File object
• Folder object
• Friend object
• Permissions object
• Photo object
• Tag object
• User object
• Video object
• Additional URL parameters

Supported HTTP verbs

The Live Connect REST API supports the standard HTTP verbs.

• GET—Returns a representation of a resource.
• POST—Adds a new resource to a collection.
• PUT—Updates a resource at the location pointed by the URL or creates a new resource, if it doesn't exist.
• DELETE—Deletes a resource.
• MOVE—Moves the location of a resource.
• COPY—Duplicates a resource.

Request URLs must reference https://apis.live.net/v5.0/, followed by the path for the object you are working with, any parameters, and finally, the access token (represented here as ACCESS_TOKEN).

https://apis.live.net/v5.0/me/albums?access_token=ACCESS_TOKEN

Top

Support for resumable downloads

Live Connect provides support for resumable downloads by using the HTTP Range header. If a download is interrupted, an app can continue the download at a later time by requesting only the byte range for the remainder of the file. This is particularly useful when downloading larger files, or in situations where network reliability is less than optimal.

Top

Understanding the objects

In the Live Connect REST API, each category of info is contained in an object. Objects consist of a combination of child objects, arrays, and values. To access a specific object, you need to know the unique path to, and in many cases, the unique ID of, that object.

The following table lists the objects that are supported by Live Connect REST API requests, along with valid object paths.

In the preceding table, replace USER_ID, CONTACT_ID, ALBUM_ID, PHOTO_ID, VIDEO_ID, AUDIO_ID, FOLDER_ID, or APPLICATION_ID with the target user ID, Contact object ID, Album object ID, Photo object ID, Video object ID, Audio object ID, Folder object ID, or Application object ID or Live Connect client ID, respectively.

In the preceding table, you can use /me as a shortcut for the signed-in user instead of specifying /USER_ID. However, you cannot use /me unless you also provide an access token.

The Live Connect REST API exchanges info between apps, Live Connect, and SkyDrive in JavaScript Object Notation (JSON) format. (Because of this, the JSON terms structure, object, array, and value are used throughout this reference.)

When your app makes a GET request for an object, the Live Connect REST API returns the requested info as a JSON-formatted structure. Similarly, when your app makes a POST or PUT request, the Live Connect REST API requires the info to be submitted to it as a JSON-formatted structure. For more info about JSON, see Introducing JSON (http://www.json.org).

Top

Query parameters

Query parameters can be added to the end of the request URL to modify the information returned in the response. The parameters described in this section are used to specify a particular subset of the response. Additional URL parameters can also be added to specify how to return the results.

Filter query parameter

You can use the filter query parameter to specify the types of items to return when requesting SkyDrive items, as shown here.

/FOLDER_ID/files?filter=albums

The following values are supported:

• albums

• audio

• folders

• photos

• videos

When specifying multiple values, use a comma-delimited list like this.

/FOLDER_ID/files?filter=videos,audio

The filter query parameter is supported for any request that returns a list of SkyDrive items, for example, queries ending in /files, or /shared.

Limit query parameter

The limit parameter restricts the number of entries returned. This example uses the limit query parameter so that the command returns only the first two of the user's contacts.

me/contacts?limit=2

You can use this parameter with the offset parameter to select specific entries within a collection.

Note  In the JSON-formatted object that's returned, you can look in the paging object for the previous and next structures to get the offset and limit parameter values of the previous and next entries.

Offset query parameter

The offset parameter specifies the first entry to return from a collection. This example uses the offset parameter with the limit parameter to return two of the user's calendar entries, starting with the third one. That is, it will return entries 3 and 4 from the user's calendar.

me/calendars?limit=2&offset=3

You can use this parameter with the limit parameter to select specific entries within a collection.

Note  In the JSON-formatted object that's returned, you can look in the paging object for the previous and next structures to get the offset and limit parameter values of the previous and next entries.

Top

Structure value options

In the following sections, the column labeled "R/W" indicates whether a value is read-only or read/write, and the column labeled "Required on create" indicates whether a value is required for the creation of an object.

Top

Activity object

The Activity object contains info about activities in a user's activity feed and status message. The Live Connect REST API supports creating Activity objects. Use the wl.share scope to create Activity objects.

The Activity object contains the following structures.

Some activity types have required and optional structures, as described in the following table.

Sharing one of these activity types without specifying its required structures will return an error.

Important  Values for Activity object structures must not exceed 512 characters, with the exception of the source structure value, which must not exceed 487 characters. If the value for either the link or source field exceeds the respective maximum limit, the call returns an error. For all other structures, values that exceed the maximum length are truncated and sent.

The following is an example of an Activity object.

{
    "message": "Explore Windows Live Hotmail",
    "link": "http://explore.live.com/windows-live-hotmail", 
    "description": "Give us 15 seconds...we'll show you the new Hotmail!",  
    "picture": "http://res2.explore.live.com/...part of URL omitted for brevity...fd39.jpg",
    "name": "Windows Live Hotmail Home"
}

To create an Activity object by using the Live Connect REST API, make a POST request to /me/share. Include the properties for the activity in the request body, as shown here.

Content-Type: application/json

{
    "message": "Explore Windows Live Hotmail",
    "link": "http://explore.live.com/windows-live-hotmail", 
    "description": "Give us 15 seconds...we'll show you the new Hotmail!",  
    "picture": "http://res2.explore.live.com/...part of URL omitted for brevity...fd39.jpg",
    "name": "Windows Live Hotmail Home"
}

Note  

If the call is successful in this example, the Live Connect REST API returns the following JSON-formatted object.

{
   "from": {
      "name": "Roberto Tamburello", 
      "id": "8c8ce076ca27823f"
   }, 
   "message": ...The message value..., 
   "link": ...The link value, if one was provided, otherwise null..., 
   "description": ...The description value, if one was provided, otherwise null..., 
   "picture": ...The picture value, if one was provided, otherwise null..., 
   "name": ...The name value, if one was provided, otherwise null..., 
   "source": ...The source value, if one was provided, otherwise null...
}

Top

Album object

The Album object contains info about a user's albums in Microsoft SkyDrive. Albums are stored at the root level of a user's SkyDrive directory, and can contain combinations of photos, videos, audio, files, and folders. The Live Connect REST API supports reading Album objects. Use the wl.photos scope to read a user's Album objects. Use the wl.skydrive scope to read a user's files. Use the wl.contacts_photos scope to read any albums, photos, videos, and audio that other users have shared with the user.

The Album object contains the following structures.

The following is an example of a collection of Album objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "album.8c8ce076ca27823f.8C8CE076CA27823F!126",
         "from": {
            "name": "Roberto Tamburello",
            "id": "8c8ce076ca27823f"
         },
         "name": "My Sample Album 1", 
         "description": "",
         "parent_id": "folder.de57f4126ed7e411",
         "upload_location": "https://apis.live.net/v5.0/folder.de57f4126ed7e411.DE57F4126ED7E411!126/files/",
         "is_embeddable": true
         "count": 4, 
         "link": "https://cid-8c8ce076ca27823f.skydrive.live.com/redir.aspx?page\u003dself\u0026resid\u003d8C8CE076CA27823F!126\u0026type\u003d5", 
         "type": "album",
         "shared_with": {
            "access": "Everyone (public)"
         },
         "created_time": "2011-04-21T23:19:47+0000", 
         "updated_time": "2011-04-22T19:18:12+0000"
      }, {
         ...
      }
   ]
}

To get a collection of Album objects by using the Live Connect REST API, make a GET request to /me/albums.

Note  To get an album's cover image, call /ALBUM_ID/picture.

To create a new Album resource, make a POST request to /me/albums. Pass the name and description attributes in the request body, as shown here.

{
   "name": "Vacation 2011",
   "description": "Photos from our fun vacation."
}

To update the properties of an Album, make a PUT request to /ALBUM_ID. Pass the attributes to update in the request body, as shown here.

{
   "name": "Maui Vacation 2011",
   "description": "Photos from our vacation on Maui."
}

To delete an album, make a DELETE request to /ALBUM_ID.

Top

Application object

The Application object contains info about a developer's client IDs that work with Live Connect. The Live Connect REST API supports reading and creating Application objects. Use the wl.applications scope to read Application objects, and use the wl.applications_create scope to create Application objects.

The ability to create, read, update, and delete Application objects is useful for providers who build comment or sign-in widgets for use by third-party websites. Supplying an application ID for each website that uses the provider’s widget enables third-party sites to provide a redirect URL for OAuth authorization and track analytics for widget usage on https://manage.dev.live.com.

The Application object contains the following structures.

The following is an example of a collection of Application objects. (For brevity, only the first object is shown.)

{
  "data": [
      {
         "id": "application.000000004c043705", 
         "name": "Pilot Live Connect App", 
         "client_id": "000000004c043705", 
         "client_secret": "O9L3tC4ecrCdLDaNsNC3m4mdiBm9gYi4", 
         "uris": [
            {
               "uri": "http://www.contoso.com", 
               "type": "web"
            }
         ], 
         "terms_of_service_link": "http://www.contoso.com/terms_of_service.php", 
         "privacy_link": "http://www.contoso.com/privacy.php",
         "picture": "https://public.dc1files.livefilestore.com/y1ppKKuiPyL82GBO149h-XhPxuPbD4iv0r-0IbITngBKpqEUShzTmxsj295NjLtLfmZxWZArsbYPG6FkhV7nKCPeg?psid=1",
         "upload_location": "https://apis.live.net/v5.0/application.000000004c043705/picture", 
         "created_time": "2011-04-18T19:03:59+0000", 
         "updated_time": "2011-04-25T18:24:26+0000"
      },  {
         ...
	     }
   ]
}

To get an Application object by using the Live Connect REST API, make a GET request to /me/applications.

To create an Application object by using the Live Connect REST API, make a POST request to /me/applications. Include the properties for the Application object in the request body, as shown here.

Content-Type: application/json

{
    "name": "Pilot Live Connect App", 
    "uri": "http://www.contoso.com",
    "terms_of_service_link": "http://www.contoso.com/terms_of_service.php", 
    "privacy_link": "http://www.contoso.com/privacy.php" 
}

Note  

If the call is successful, the Live Connect REST API returns the following JSON-formatted object.

{
    "id": "application.000000004c043705", 
    "name": "Pilot Live Connect App", 
    "client_id": "000000004c043705", 
    "client_secret": "O9L3tC4ecrCdLDaNsNC3m4mdiBm9gYi4", 
    "uris": [
        {
            "uri": "http://www.contoso.com", 
            "type": "web"
        }
    ], 
    "terms_of_service_link": "http://www.contoso.com/terms_of_service.php", 
    "privacy_link": "http://www.contoso.com/privacy.php",
    "picture": null
    "upload_location": "https://apis.live.net/v5.0/application.000000004c043705/picture",
    "created_time": "2011-04-18T19:03:59+0000", 
    "updated_time": "2011-04-25T18:24:26+0000"
}

To get an application’s logo, make a GET request to APPLICATION_ID/picture, where APPLICATION_ID is the value of the id structure, for example, application.000000004c043705/picture. A link to the location of the application’s logo is returned in the redirect response’s Location header. If you set the suppress_redirects query string parameter to true, as in application.000000004c043705/picture?suppress_redirects=true, a JSON object is returned in the response's body. This object has a single location structure whose value is a link that points to the location of the application’s logo.

To upload an application's logo, make a POST or a PUT request to APPLICATION_ID/picture, or to the value of the location structure within the response to a GET call to /APPLICATION_ID/picture?suppress_redirects=true. For more info about POST and PUT operations, see the "Uploading files" section of Folders and files.

Note  When uploading an application's logo, the overwrite query-string parameter and the logo's filename, if provided, are ignored. Also, only logos in Portable Network Graphics (PNG) and Graphics Interchange Format (GIF) file formats, of size 48 × 48 pixels, can be uploaded.

Top

Audio object

The Audio object contains info about a user's audio in SkyDrive. The Live Connect REST API supports creating, reading, updating, and deleting Audio objects. Use the wl.skydrive scope to read Audio objects. Use the wl.contacts_skydrive scope to read any audio that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete Audio objects.

The Audio object contains the following structures.

The following is an example of a collection of Audio objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!144", 
         "from": {
            "name": "Stig Struve-Christensen", 
            "id": "a6b2a7e8f2515e5e"
         }, 
         "name": "SampleAudio.mp3", 
         "description": null, 
         "parent_id": "folder.a6b2a7e8f2515e5e", 
         "size": 8414449,
         "upload_location": "https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!144/content/",  
         "comments_count": 0, 
         "comments_enabled": false, 
         "is_embeddable": false, 
         "source": "http://storage.live.com/s1p60U8Xs4UzIXTScrTioalE-ZaVFiDQBA15MS2BwcsuNjfG64Z2fw-DAjXnPuqC47YR40_xAoPD8aRGhtna9ZFZ9_oO4BTz4CWF973DTXMxc5U3TntcQ9qEA/SampleAudio.mp3:Binary", 
         "link": "https://skydrive.live.com/redir.aspx?cid\u003d22688711f5410e6c\u0026page\u003dview\u0026resid\u003d22688711F5410E6C!582\u0026parid\u003d22688711F5410E6C!581",
         "type": "audio",
         "title": "My Sample Audio",
         "artist": "My Favorite Artist",
         "album": "My Favorite Album",
         "album_artist": "My Favorite Artist", 
         "genre": "Easy Listening", 
         "duration": 225000,
         "picture": "https://storage.live.com/items/A6B2A7E8F2515E5E!144:MobileReady/SampleAudio.mp3?psid=1&ck=0&ex=720"   
         "shared_with": {
            "access": "Just me"
         }, 
         "created_time": "2012-09-23T22:00:57+0000", 
         "updated_time": "2012-09-03T22:00:57+0000"
      }, {
         ...
      }
   ]      
}

To create a new Audio resource, you can make either a PUT request with the audio in the body or a POST request with the audio in a multipart form body. For POST, make a POST request to the /UPLOAD_LOCATION for the target folder, or a POST request to /FOLDER_ID/files. You must format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data, and specify the boundary like this.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the audio as the value of the filename parameter of the Content-Disposition header, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="file"; filename="SampleAudio.wav"
Content-Type: audio/mp3

...contents of SampleAudio.wav...
--AaB03x--

Note  

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

Only one multipart section per request is supported. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created audio, and the response body contains the following properties.

{
   "id": "ID of the new audio",
   "name": "The file's name and file extension",
   "source": "URL where the audio can be downloaded from"
}

You can upload an audio to an existing resource in any of the following ways.

• Make a PUT request to /UPLOAD_LOCATION/FILE_NAME for the folder you would like to upload to.

• Make a PUT request to /FOLDER_ID/files/FILE_NAME.

• Make a PUT request to /ALBUM_ID/files/FILE_NAME.

• Make a PUT request to /UPLOAD_LOCATION for the file to update.

• Make a PUT request to /AUDIO_ID/content.

To update the properties for an Audio resource, make a PUT request to /AUDIO_ID, and specify the changes in the request body, as shown here.

{
   "name": "SampleAudioChanged.wav"
   "description": "Holiday Concert"
}

To delete an audio, make a DELETE request to /AUDIO_ID.

To move an audio, make a MOVE request to /AUDIO_IF or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy an audio, make a COPY request to /AUDIO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let SkyDrive choose the uploaded file's new file name. Note that MOVE and COPY do not support overwriting at this time.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the audio exists, it is overwritten. If the value is set to false, the audio is not overwritten, and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

Top

Calendar object

The Calendar object contains info about a user's Outlook.com calendar. The Live Connect REST API supports creating, reading, updating, and deleting calendars. Use the wl.calendars scope to read a user's Calendar objects. Use the wl.calendars_update scope to create Calendar objects for a user. Use the wl.contacts_calendars scope to read a user's friends' Calendar objects.

The Calendar object contains the following structures.

The following is an example of a collection of Calendar objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "calendar.42d4dbc866f94c83849c88c6eb9985bc", 
         "name": "Birthday calendar", 
         "description": "If you have birthdays listed for your contacts, they'll appear on this calendar. You can add more birthdays, but you can't add other types of events.", 
         "created_time": "2011-08-05T19:41:04+0000", 
         "updated_time": "2011-08-05T19:41:04+0000", 
         "from": {
            "name": null, 
            "id": null
         }, 
         "is_default": false, 
         "subscription_location": null, 
         "permissions": "read"
      },{
         ...
      }
   ]
}

To get a collection of Calendar objects by using the Live Connect REST API, make a GET request to either /me/calendars, or /USER_ID/calendars.

To get the properties for a particular Calendar object, make a GET request with the ID of the calendar.

https://apis.live.net/v5.0/calendar.b4466224b2ca42798c3d4ea90c75aa56?access_token=ACCESS_TOKEN

To create a new Calendar, make a POST request to either /me/calendars, or /USER_ID/calendars. Pass the name (required) and summary (optional) strings as properties in the request body. The properties for the new calendar are returned in the response body, and the Location header contains the URI for the newly created calendar.

{
   "name": "Summer Events",
   "summary": "Things we are doing this summer."
}

Warning  

The request body must not include the subscription_location property.

To subscribe to a public calendar, make a POST request to either /me/calendars or /USER_ID/calendars. Pass the name and subscription_location strings as properties in the request body. The value of subscription_location must be a valid online iCal calendar. Both properties are required.

{
   "name": "Soccer League"
   "subscription_location": "ical.sharedcalendars.com/98754auv"
}

To update a Calendar, make a PUT request to /CALENDAR_ID. Include the properties to update in the request body, as shown here.

{
   "name": "Fall Happenings"
}

To delete a Calendar, make a DELETE request to /CALENDAR_ID.

In the preceding examples, replace CALENDAR_ID with the target calendar ID.

Top

Comment object

The Comment object contains info about comments that are associated with a photo, audio, or video on SkyDrive. The Live Connect REST API supports reading Comment objects. Use the wl.photos scope to read Comment objects. Use the wl.contacts_photos scope to read the Comment objects that are associated with any albums, photos, and videos that other users have shared with the user.

The Comment object contains the following structures.

The following is an example of a collection of Comment objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "comment.22688711f5410e6c.22688711f0410e6c!818.22688711F5410E6C!979",
         "from": {
            "name": "Roberto Tamburello", 
            "id": "8c8ce076ca27823f"
         }, 
         "message": "A lighthouse built on some rocks.", 
         "created_time": "2011-04-21T23:21:28+0000"
      }, {
         ...
      }
   ]
}

To get a collection of Comment objects by using the Live Connect REST API, make a GET request to /RESOURCE_ID/comments.

Top

Contact object

The Contact object contains info about a user's Outlook.com contacts. The Live Connect REST API supports reading Contact objects.

The Contact object contains the following structures.

When creating a new Contact object, at least one of the following attributes must be provided. These are marked as Optional in the preceding structures table.

• first_name
• last_name
• preferred (User object, emails structure)
• personal (User object, emails structure)
• business (User object, emails structure)
• other (User object, emails structure)
• name (User object, work array, employer structure)

The preferred, personal, business, other, and name structures belong to the User object. These attributes are not returned when getting a Contact object instance. However, it is possible to add these attributes when creating a new Contact object. Although the value cannot be directly returned, this behavior is handy in situations when you add a new contact by email address only, or if you want to create a contact that is a company. To ensure that the company name or email address appear in place of the contact name, omit the first_name and last_name fields. The email address or company name that you specify appears in place of the name in the returned Contact object instance.

Use the following JSON as a guide for defining the attributes in your request.

{
   "first_name": "",
   "last_name": "",
   "emails": {
      "preferred": "",
      "personal": "",
      "business": "",
      "other": ""
   },
   "work": [
      {
         "employer": {
            "name": ""
         }
      }
   ]
}

The following is an example of a collection of Contact objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "contact.b4466224b2ca42798c3d4ea90c75aa56", 
         "first_name": "Henrik", 
         "last_name": "Jensen", 
         "name": "Henrik Jensen", 
         "gender": null, 
         "is_friend": false, 
         "is_favorite": false, 
         "user_id": null, 
         "email_hashes": [
            "9ecdb19f4eb8e04304c5d1280368c42e85b6e4fe39f08b0c837ec592b905a620", 
            "fc05492f50da6488aa14dcf221d395bcb29a4e43b43b250d60c68df4f831cad3"
         ], 
         "updated_time": "2011-04-22T00:11:13+0000", 
         "birth_day": 29, 
         "birth_month": 3 
         
      }, {
         ...
      }
   ]
}

To get a collection of Contact objects by using the Live Connect REST API, make a GET request to /me/contacts.

Note  

If a Contact references a user, you can return a User object by making a GET request using the user_id value for the Contact.

To redirect a GET call to the URL of the picture of a contact who is a user, call /USER_ID/picture. (A User object's ID is not the same as a contact ID.)

Top

Error object

The Error object contains info about an error that is returned by the Live Connect APIs.

The Error object contains the following structures.

The following is an example of an Error object.

{
   "error": {
      "code": "request_token_expired", 
      "message": "The provided access token has expired."
   }
}

Top

Event object

The Event object contains info about events on a user's Outlook.com calendars. The Live Connect REST API supports creating Event objects. Use the wl.events_create scope to create Event objects on the user's default calendar only. Use the wl.calendars scope to read Event objects on the user's calendars. Use wl.calendars_update to create Event objects on any of the user's calendars. Use the wl.contacts_calendars scope to read Event objects from the user's friend's calendars.

The Event object contains the following structures.

The following is an example of an Event object.

{
   "id": "event.611afb17fa9448f28cdb8277e8ffeb77.e9f015000d0249ce847c5306a25d7d75", 
   "name": "Global Project Risk Management Meeting", 
   "description": "Generate and assess risks for the project",
   "calendar_id": "calendar.611afb17fa9448f28cdb8277e8ffeb77",
   "from": {
      "name": "William Flash",
      "id": "de57f4126ed7e411"
   }, 
   "start_time": "2011-04-20T01:00:00+0000", 
   "end_time": "2011-04-20T02:00:00+0000", 
   "location": "Building 81, Room 9981, 123 Anywhere St., Redmond WA 19599", 
   "is_all_day_event": false, 
   "is_recurrent": false,
   "recurrence": null,
   "reminder_time": null,
   "availability": "busy", 
   "visibility": "public", 
   "created_time": "2011-03-14T23:01:31+0000",
   "updated_time": "2011-04-19T20:23:03+0000"
}

To return a list of events for a calendar by using the Live Connect REST API, make a GET request to /CALENDAR_ID/events. This will return all events between now and the next 30 days by default.

To return a list of events for a user, make a GET request to either /me/events, or /USER_ID/events.

To retrieve the properties for an Event, make a GET request to /EVENT_ID.

To create an Event object on the user's default calendar by using the Live Connect REST API, make a POST request to /me/events. Pass the properties for the event in the request body, as shown here.

Content-Type: application/json

{
    "name": "Global Project Risk Management Meeting",
    "description": "Generate and assess risks for the project",
    "start_time": "2011-04-20T01:00:00-07:00",
    "end_time": "2011-04-20T02:00:00-07:00",
    "location": "Building 81, Room 9981, 123 Anywhere St., Redmond WA 19599",
    "is_all_day_event": false,
    "availability": "busy",
    "visibility": "public"
}

Note  

If the call is successful, the Live Connect REST API returns the following JSON-formatted object.

{
   "name": "Global Project Risk Management Meeting", 
   "description": "Generate and assess risks for the project", 
   "start_time": "2011-04-20T01:00:00+0000", 
   "end_time": "2011-04-20T02:00:00+0000", 
   "location": "Building 81, Room 9981, 123 Anywhere St., Redmond WA 19599", 
   "is_all_day_event": false,
   "is_recurrent": false,
   "recurrence": null,
   "reminder_time": null, 
   "availability": "busy", 
   "visibility": "public", 
   "updated_time": "2011-04-19T20:23:03+0000"
}

To delete an Event, make a DELETE request to /EVENT_ID.

Tip  

The Live Connect REST API does not support creating or updating recurring events; however, you can delete recurring events the same way you would delete a nonrecurring event. Deleting a recurring event deletes all of its occurrences.

Top

File object

The File object contains info about a user's files in SkyDrive. The Live Connect REST API supports creating, reading, updating, and deleting File objects. Use the wl.skydrive scope to read File objects. Use the wl.contacts_skydrive scope to read any files that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete File objects.

The File object contains the following structures.

The following is an example of a File object.

{
   "data": [
      {
         "id": "file.22688711f5410e6c.22688711F5410E6C!942", 
         "from": {
            "name": "William Flash", 
            "id": "22688711f5410e6c"
         }, 
         "name": "Processing.docx", 
         "description": null, 
         "parent_id": "folder.22688711f5410e6c.22688711F5410E6C!479", 
         "size": 12692, 
         "upload_location": "https://apis.live.net/v5.0/file.22688711f5410e6c.22688711F5410E6C!942/content/", 
         "comments_count": 0, 
         "comments_enabled": true, 
         "is_embeddable": false, 
         "source": "http://storage.live.com/s1pEwo9qzyT4_BJZqMNm-aVzgLo-WRsQGzjzFsXjyREuQG5pDYr237vKz3i2pmqFuniYPzsuIZAOCUMB_gdfKCUpLpVcaAMXGrk4T7jOWenRniCv9vex7GWfSvy-XCVBVnU/Processing.docx:Binary", 
         "link": "https://skydrive-df.live.com/redir.aspx?cid\u003d22688711f5410e6c\u0026page\u003dview\u0026resid\u003d22688711F5410E6C!942\u0026parid\u003d22688711F5410E6C!479", 
         "type": "file", 
         "shared_with": {
            "access": "Everyone (public)"
         }, 
         "created_time": "2011-10-12T23:18:23+0000", 
         "updated_time": "2011-10-12T23:18:23+0000"
      },{
         ...
      }
   ]
}

To get properties for a File resource, make a GET request to /FILE_ID (the target file ID).

To download the content of a File resource, make a GET request to/FILE_ID/content. The file content is returned in the response body.

Tip  You can instruct the user's web browser to prompt the user to save the file that's being downloaded instead of having the web browser try to download and display the file directly in the browser. To do this, add the download=true query parameter after /content (for example, FILE_ID/content?download=true). The download=true query parameter works for all calls related to SkyDrive that redirect to content or to returning URLs that point to content. For example, FOLDER_ID/files?download=true causes all source and thumbnail URLs in the response to be treated also as download links when they are used.

To return a download link for a File resource, make a GET request to /FILE_ID/content with the suppress_redirects=true parameter. The URL is returned in the response body in the following format.

{
   "location": "..."
}

Tip  If the client has already requested the properties for a file, the download link will be in the source field.

To create a new File resource, you can either make a PUT request with the file in the body, or you can make a POST request with the file in a multipart form body. You can make a POST request to the /UPLOAD_LOCATION for the target folder, a POST request to /FOLDER_ID/files, or a PUT request to /FOLDER_ID/files/<file name>. For a POST request, you must also format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data, and specify the boundary like this.

Important  On platforms that support the PUT request, use PUT whenever possible to upload files to SkyDrive to avoid errors that can occur when POST is used.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the file as the value of the filename parameter of the Content-Disposition header, as shown here.

--AaB03x
Content-Disposition: form-data; name="file"; filename="file1.txt"
Content-Type: text/plain

...contents of file1.txt...
--AaB03x--

Note  

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

We support only one multipart section per request. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created file, and the response body contains the following properties.

{
   "id": "ID of the new file",
   "name": "The file's name and file extension",
   "source": "URL where the file can be downloaded from"
}

You can instruct SkyDrive to return an HTML response that can be used inside a web browser after the file is created. You can also attach a unique identifier to each upload request so that you can identify a particular upload if you are uploading multiple files in quick succession, which is especially useful for <form> multipart posts. To do this, use a POST multipart/form-data request, like this.

POST https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110/files?state=MyNewFileState&redirect_uri=http%3A%2F%2Fwww.contoso.com%2Fcallback.htm&access_token=ACCESS_TOKEN

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="file"; filename="MyNewFile.txt"
Content-Type: text/plain

These are the contents of my new file.
--AaB03x--

In this example, replace the folder ID with your target folder ID; replace the state query-string parameter value with your unique identifier; and replace the redirect_uri query-string parameter with the path to your callback page. Note that the domain portion of the path must match the redirect domain that you specified in the Live Connect app management site for the corresponding client ID.

SkyDrive returns HTML-formatted code similar to the following.

<html>
    <head>
        <script type="text/javascript">
            window.location = "http://www.contoso.com/callback.htm#state=MyNewFileState&result=%7B%22id%22%3A%22file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!184%22%2C%22source%22%3A%22http%3A%2F%2Fstorage.live.com%2Fs1pasGKzgXFvuEQCbxGtOyIpboUVH1OCHoRzUJNDDwL0zVoidb0RRrNVk88hUrOEve5OMT7eCkuxPbop7dV9tMJQ-eE8SCQ28vFv9ZgPnDGwQMRm-0FeG3-KEY4HL9dQSw9%2FMyNewFile.txt%3ABinary%2CDefault%2FMyNewFile.txt%22%7D";
        </script>
    </head>
</html>

When decoded, the result response parameter is similar to this.

{
    "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!184",
    "name: "MyNewFile.txt",
    "source": "http://storage.live.com/s1pasGKzgXFvuEQCbxGtOyIpboUVH1OCHoRzUJNDDwL0zVoidb0RRrNVk88hUrOEve5OMT7eCkuxPbop7dV9tMJQ-eE8SCQ28vFv9ZgPnDGwQMRm-0FeG3-KEY4HL9dQSw9/MyNewFile.txt:Binary,Default/MyNewFile.txt"
}

You can upload a file to an existing resource in any of the following ways.

• Make a PUT request to /UPLOAD_LOCATION/FILE_NAME of the parent folder's ID.

• Make a PUT request to /FOLDER_ID/files/FILE_NAME.

• Make a PUT request to /UPLOAD_LOCATION for the file to update.

• Make a PUT request to /FILE_ID/content.

To update the properties for a File resource, make a PUT request to /FILE_ID, and specify the changes in the request body, as shown here. In this example, both the file name and the description are updated. Note that the filename extension is required when updating the file name.

{
   "name": "UFO_Sightings_1979.docx"
   "description": "The detailed accounts of all UFO sightings in 1979."
}

To delete a file, make a DELETE request to /FILE_ID.

To move a file, make a MOVE request to /FILE_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy a file, make a COPY request to /FILE_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let SkyDrive choose the uploaded file's new file name.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the file exists, it is overwritten. If the value is set to false, the file is not overwritten and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

In all of the preceding cases, you can replace FILE_ID with either me/skydrive/FRIENDLY_FOLDER_NAME or USER_ID/skydrive/FRIENDLY_FOLDER_NAME, where me represents the current consenting user, USER_ID represents the consenting user's ID, and FRIENDLY_FOLDER_NAME represents an allowed friendly folder name like my_documents to represent the Documents folder. For more info, see the Common tasks in accessing Microsoft SkyDrive from your app topic's "Using friendly names to access certain SkyDrive folders" section.

Tip  Before uploading a file, have your app check to make sure that there is enough available SkyDrive storage space by making a GET call to USER_ID/skydrive/quota. For example, your app could get the size of the file in bytes and then compare it to the number of available storage bytes returned in the SkyDrive quota call. For more info, see Common tasks in accessing Microsoft SkyDrive from your app, in the "Getting a user's total and remaining SkyDrive storage quota" section.

Top

Folder object

The Folder object contains info about a user's folders in SkyDrive. Folders can contain combinations of photos, videos, audio, and subfolders. The Live Connect REST API supports reading Folder objects. Use the wl.photos scope to read Folder objects. Use the wl.contacts_photos scope to read any albums, photos, videos, and audio that other users have shared with the user.

The Folder object contains the following structures.

The following is an example of a collection of Folder objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "folder.8c8ce076ca27823f.8C8CE076CA27823F!142", 
         "from": {
            "name": "Roberto Tamburello", 
            "id": "8c8ce076ca27823f"
         }, 
         "name": "My Sample Folder in Album 1", 
         "description": "",
         "parent_id": "folder.de57f4126ed7e411", 
         "upload_location": "https://apis.live.net/v5.0/folder.de57f4126ed7e411.DE57F4126ED7E411!126/files/", 
         "is_embeddable": true, 
         "count": 3, 
         "link": "https://cid-8c8ce076ca27823f.skydrive.live.com/redir.aspx?page\u003dself\u0026resid\u003d8C8CE076CA27823F!142\u0026parid\u003d8C8CE076CA27823F!126\u0026type\u003d5", 
         "type": "folder", 
         "shared_with": {
             "access": "Just me"
         },
         "created_time": "2011-04-22T00:36:30+0000", 
         "updated_time": "2011-04-22T19:18:12+0000"
      }, {
         ...
      }
   ]
}

To get the root Folder resource by using the Live Connect REST API, make a GET request to either /me/skydrive or /USER_ID/skydrive.

To get a subfolder resource, make a GET request to /FOLDER_ID.

To enumerate the contents of a folder, make a GET request to /FOLDER_ID/files.

A folder may contain the following objects.

• Folder object
• File object
• Album object
• Photo object
• Video object
• Audio object

To create a new Folder resource, make a POST request to /FOLDER_ID. Pass the name and description attributes in the request body, as shown here.

{
   "name": "Informative Spreadsheets",
   "description": "A folder full of useful data visualizations."
}

The folder is created as a child of the folder that is specified in the request URL. The location header points to the newly created folder location, and the response body contains properties for the newly created folder.

To update the properties of a Folder, make a PUT request to /FOLDER_ID. Pass the attributes to update in the request body, as shown here.

{
   "name": "Very Informative Spreadsheets",
   "description": "A folder full of even more useful data visualizations."
}

To delete a folder, make a DELETE request to /FOLDER_ID.

In the preceding examples, replace FOLDER_ID with the target folder ID.

Top

Friend object

The Friend object contains info about a user's friends. A Friend object represents a user's contact whose is_friend value is set to true. The Live Connect REST API supports reading Friend objects.

The Friend object contains the following structures.

The following is an example of a collection of Friend objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "d09ea18fafc39a0c", 
         "name": "Henrik Jensen" 
      }, {
         ...
      }
   ]
}

To get a collection of Friend objects by using the Live Connect REST API, make a GET request to /me/friends.

Top

Permissions object

The Permissions object contains a list of scopes, showing those scopes to which the user has consented. The response body contains a JSON object that lists all consented scopes as a name/value pair. Each scope to which the user consented is present as a key.

The following is an example of a Permissions object. (For brevity, not all scopes are shown.)

{
   "data": [
        {         
            "wl.basic": 1,
            "wl.offline_access": 1,
            "wl.signin": 1,
            ...
        }
    ]
}

To get a Permissions object by using the Live Connect REST API, make a GET request to /me/permissions.

Top

Photo object

The Photo object contains info about a user's photos on SkyDrive. The Live Connect REST API supports creating, reading, updating, and deleting Photo objects. Use the wl.photos scope to read Photo objects. Use the wl.contacts_photos scope to read any albums, photos, videos, and audio that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete Photo objects.

Note  

Photos that are uploaded to SkyDrive through the API are limited to a maximum resolution of 2048 x 2048 pixels. Any photo over that resolution is scaled proportionally to fit within a maximum size of 2048 x 2048 pixels.

The Photo object contains the following structures.

The following is an example of a collection of Photo objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "file.de57f4126ed7e411.DE57F4126ED7E411!128", 
         "from": {
            "name": "Nuno Bento", 
            "id": "de57f4126ed7e411"
         }, 
         "name": "Maui-2012_0034.JPG", 
         "description": null, 
         "parent_id": "folder.de57f4126ed7e411.DE57F4126ED7E411!126", 
         "size": 561683, 
         "comments_count": 1, 
         "comments_enabled": true, 
         "tags_count": 0, 
         "tags_enabled": true,
         "is_embeddable": true, 
         "picture": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:Thumbnail", 
         "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:HighRes", 
         "upload_location": "https://apis.live.net/v5.0/file.de57f4126ed7e411.DE57F4126ED7E411!128/content/", 
         "images": [
            {
               "height": 450, 
               "width": 600, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:WebReady", 
               "type": "normal"
            }, {
               "height": 132, 
               "width": 176, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:MobileReady", 
               "type": "album"
            }, {
               "height": 72, 
               "width": 96, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:Thumbnail", 
               "type": "thumbnail"
            }, {
               "height": 1200, 
               "width": 1600, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:HighRes", 
               "type": "full"
            }
         ], 
         "link": "https://skydrive.live.com/redir.aspx?cid\u003dde57f4126ed7e411\u0026page\u003dview\u0026resid\u003dDE57F4126ED7E411!128\u0026parid\u003dDE57F4126ED7E411!126", 
         "when_taken": "2008-03-24T23:41:53+0000", 
         "height": 1200, 
         "width": 1600, 
         "type": "photo",
         "location": {
             "latitude": 47.65316, 
             "longitude": -122.135911,
             "altitude": 43
         }, 
         "camera_make": "MyManufacturer",
         "camera_model": "MyModel",
         "focal_ratio": 2.8,
         "focal_length": 3.85,
         "exposure_numerator": 1,
         "exposure_denominator": 15, 
         "shared_with": {
            "access": "Everyone (public)"
         }, 
         "created_time": "2012-12-03T18:14:03+0000", 
         "updated_time": "2012-12-03T18:31:01+0000"
      }, {
         ...
      }
   ]      
}

To get a collection of Photo objects by using the Live Connect REST API, make a GET request to /ALBUM_ID/files.

Note  You can also get a collection of Photo objects by calling either /ALBUM_ID/photos, or /FOLDER_ID/photos.

Note  To display a photo, call /PHOTO_ID/picture. To display a photo of a specific image size, follow /PHOTO_ID/picture with ?type= and one of the following: thumbnail, small, album, normal, or full. The default is normal. The following is an example of a call that displays a thumbnail image.

https://apis.live.net/v5.0/PHOTO_ID/picture?type=thumbnail&access_token=ACCESS_TOKEN

In the preceding examples, replace ALBUM_ID and PHOTO_ID with the target album or photo ID.

To create a new Photo resource, you can make either a PUT request with the photo in the body or a POST request with the photo in a multipart form body. For POST, make a POST request to the /UPLOAD_LOCATION for the target folder or a POST request to /FOLDER_ID. You must format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data, and specify the boundary like this.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the photo as the value of the filename parameter of the Content-Disposition header, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="file"; filename="hovering_orbs.jpg"
Content-Type: image/jpeg

...contents of hovering_orbs.jpg...
--AaB03x--

Note  

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

Only one multipart section per request is supported. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created photo, and the response body contains the following properties.

{
   "id": "ID of the new photo",
   "name": "The file's name and file extension",
   "source": "URL where the photo can be downloaded from"
}

You can upload a photo to an existing resource in any of the following ways.

• Make a PUT request to /UPLOAD_LOCATION/FILE_NAME for the folder you would like to upload to.

• Make a PUT request to /FOLDER_ID/files/FILE_NAME.

• Make a PUT request to /ALBUM_ID/files/FILE_NAME.

• Make a PUT request to /UPLOAD_LOCATION for the file to update.

• Make a PUT request to /PHOTO_ID/content.

By default, if an uploaded photo is larger than 2048 × 2048 pixels in size, SkyDrive automatically attempts to shrink it to fit within this 2048 × 2048-pixel size constraint. To override this behavior, set the downsize_photo_uploads query-string parameter to false—for example, /FOLDER_ID/files?downsize_photo_uploads=false for POST or /FOLDER_ID/files/FILENAME?downsize_photo_uploads=false for PUT.

To update the properties for a Photo resource, make a PUT request to /PHOTO_ID, and specify the changes in the request body, as shown here.

{
   "name": "fast-moving_orbs.jpg"
   "description": "Fast moving objects."
}

To delete a photo, make a DELETE request to /PHOTO_ID.

To move a photo, make a MOVE request to /PHOTO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy a photo, make a COPY request to /PHOTO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let SkyDrive choose the uploaded file's new file name. Note that MOVE and COPY do not support overwriting at this time.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the file exists, it is overwritten. If the value is set to false, the file is not overwritten, and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

Top

Tag object

The Tag object contains info about tags that are associated with a photo or a video on SkyDrive. The Live Connect REST API supports reading Tag objects. Use the wl.photos, and wl.skydrive scopes to read Tag objects. Use the wl.contacts_photos and wl.contacts_skydrive scopes to read the Tag objects that are associated with any photos that other users have shared with the user.

The Tag object contains the following structures.

The following is an example of a collection of Tag objects. (For brevity, only the first object is shown.)

{
    "id": "tag.22688711f5410e6c.22688711f5410e6c!767.PRaXZrdHI1uYGQYi9CU0StrzHak",
    "user": {
        "name": "Roberto Tamburello",
        "id": "8c8ce076ca27823f"
    },
    "x": 43.8986,
    "y": 54.4138,
    "created_time": "2011-04-22T01:17:00+0000"
}

Note  

Information about the tagged user is stored in the user attribute.

The x and y members are not present on tags that are returned from a video object.

To get a collection of Tag objects by using the Live Connect REST API, make a GET request to /RESOURCE_ID/tags.

Top

User object

The User object contains info about a user. The Live Connect REST API supports reading User objects.

The User object contains the following structures.

The following is an example of a User object.

{
   "id": "8c8ce076ca27823f", 
   "name": "Roberto Tamburello", 
   "first_name": "Roberto", 
   "last_name": "Tamburello", 
   "link": "http://cid-8c8ce076ca27823f.profile.live.com/", 
   "birth_day": 20, 
   "birth_month": 4, 
   "birth_year": 2010, 
   "work": [
      {
         "employer": {
            "name": "Microsoft Corporation"
         }, 
         "position": {
            "name": "Software Development Engineer"
         }
      }
   ], 
   "gender": "male", 
   "emails": {
      "preferred": "Roberto@contoso.com",
      "account": "Roberto@contoso.com", 
      "personal": "Roberto@fabrikam.com", 
      "business": "Robert@adatum.com",
      "other": "Roberto@adventure-works.com"
   },
   "addresses": {
      "personal": {
         "street": "123 Main St.", 
         "street_2": "Apt. A", 
         "city": "Redmond", 
         "state": "WA", 
         "postal_code": "12990", 
         "region": "United States"
      }, 
      "business": {
         "street": "456 Anywhere St.", 
         "street_2": "Suite 1", 
         "city": "Redmond", 
         "state": "WA", 
         "postal_code": "12399", 
         "region": "United States"
      }
   }, 
   "phones": {
      "personal": "(555) 555-1212", 
      "business": "(555) 111-1212", 
      "mobile": null
   }, 
   "locale": "en_US", 
   "updated_time": "2011-04-21T23:55:34+0000"
}

To get a User object by using the Live Connect REST API, make a GET request to either /me, or /USER_ID.

Note  To redirect a GET call to the URL of a user's picture, you can call /me/picture or /USER_ID/picture. You can get different sizes of a user's picture, if they exist, by calling /me/picture?type=SIZE or /USER_ID/picture?type=SIZE, where SIZE is one of the following: small (to get a 96 × 96-pixel picture), medium (180 × 180), or large (360 × 360). If a particular size picture doesn't exist, the next-largest size picture that's available is returned. In any event, a 96 × 96-pixel picture is returned (unless no picture is associated with the user, in which case a default user picture is returned).

Top

Video object

The Video object contains info about a user's videos on SkyDrive. The Live Connect REST API supports creating, reading, updating, and deleting Video objects. Use the wl.photos scope to read Video objects. Use the wl.contacts_photos scope to read albums, photos, and videos that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete Video objects.

The Video object contains the following structures.

The following is an example of a collection of Video objects. (For brevity, only the first object is shown.)

{
    "data": [
      {
         "id": "file.de57f4126ed7e411.DE57F4126ED7E411!135", 
         "from": {
            "name": "Nuno Bento", 
            "id": "de57f4126ed7e411"
         }, 
         "name": "Wildlife.wmv", 
         "description": null, 
         "parent_id": "folder.de57f4126ed7e411.DE57F4126ED7E411!126", 
         "size": 26246026, 
         "comments_count": 0, 
         "comments_enabled": true, 
         "tags_count": 0, 
         "tags_enabled": true, 
         "is_embeddable": true,
         "picture": "http://storage.live.com/s1pKk5vzd-gdPaJ5Q1MKN34itsyRlUkAYzD_zsr0Dg-5r4bH8Qo8XRgsunA0M-V4G-XPpu1spowx4xwfjCuDcWQVa7aWld2WCdfeWjBK_coPqaQqzoE26BJP3OZAITB5i_DRPK8jK3ZLilSbNJd-onrOA/Wildlife.wmv:Thumbnail", 
         "source": "http://storage.live.com/s1pKk5vzd-gdPaJ5Q1MKN34itsyRlUkAYzD_zsr0Dg-5r4bH8Qo8XRgsunA0M-V4G-XPpu1spowx4xwfjCuDcWQVa7aWld2WCdfeWjBK_coPqaQqzoE26BJP3OZAITB5i_DRPK8jK3ZLilSbNJd-onrOA/Wildlife.wmv:VideoMain", 
         "upload_location": "https://apis.live.net/v5.0/file.de57f4126ed7e411.DE57F4126ED7E411!135/content/", 
         "link": "https://skydrive.live.com/redir.aspx?cid\u003dde57f4126ed7e411\u0026page\u003dview\u0026resid\u003dDE57F4126ED7E411!135\u0026parid\u003dDE57F4126ED7E411!126", 
         "height": 720, 
         "width": 1280, 
         "duration": 30093, 
         "bitrate": 5942130, 
         "type": "video", 
         "shared_with": {
            "access": "Everyone (public)"
         }, 
         "created_time": "2011-08-23T23:41:18+0000", 
         "updated_time": "2011-08-23T23:41:32+0000"
      }, {
         ...
      } 
   ]
}

To get a collection of Video objects by using the Live Connect REST API, make a GET request to /ALBUM_ID/files.

Note  You can also get a collection of Video objects by calling either /ALBUM_ID/videos, or /FOLDER_ID/videos.

In the preceding examples, replace ALBUM_ID with the target Live Connect album ID.

To create a new Video resource, you can make either a PUT request with the video in the body or a POST request with the video in a multipart form body. For POST, make a POST request to the /UPLOAD_LOCATION for the target folder or a POST request to /FOLDER_ID. You must format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data and specify the boundary, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the photo as the value of the filename parameter of the Content-Disposition header, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="file"; filename="strange_lights.avi"
Content-Type: video/x-msvideo

...contents of strange_lights.avi...
--AaB03x--

Note  

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

Only one multipart section per request is supported. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created video, and the response body contains the following properties.

{
   "id": "ID of the new video",
   "name": "The file's name and file extension",
   "source": "URL where the video can be downloaded from"
}

You can upload a video to an existing resource in any of the following ways.

• Make a PUT request to /UPLOAD_LOCATION/FILE_NAME of the parent folder's ID.

• Make a PUT request to /FOLDER_ID/files/FILE_NAME.

• Make a PUT request to /ALBUM_ID/files/FILE_NAME.

• Make a PUT request to /UPLOAD_LOCATION for the file to update.

• Make a PUT request to /VIDEO_ID/content.

To update the properties for a Video resource, make a PUT request to /VIDEO_ID, and specify the changes in the request body, as shown here.

{
   "name": "triangle_formation.avi"
   "description": "Sightings of UFOs in triangle formation."
}

To delete a video, make a DELETE request to /VIDEO_ID.

To move a video, make a MOVE request to /VIDEO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy a video, make a COPY request to /VIDEO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let SkyDrive choose the uploaded file's new file name.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the file exists, it is overwritten. If the value is set to false, the file is not overwritten and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

Top

Additional URL parameters

You can specify additional parameters, as part of the URL of a GET request to the Live Connect REST API, to instruct the Live Connect APIs how to return its results. The following table explains these parameters.

For example, the following URL makes a GET request for the user's contacts list, with the pretty parameter set to false.

https://apis.live.net/v5.0/me/contacts?pretty=false&access_token=ACCESS_TOKEN

Top

Build date: 5/15/2013