MySpace Developer Platform

A Place For Developers
From MySpace Open Platform: Documentation Wiki

OpenSocial v0.9 Albums

Jump to: navigation, search

Contents

Base URI

The base uri for Albums on MySpace is http://opensocial.myspace.com/roa/09/albums. This endpoint supports GETs, PUTs, and POSTs.

URI Parameters

The URI accepts parameters as part of the URI. URIs are of the following forms

{personId}

This can be one of the following values:

  • @me: Refers to the current user. @me can only be passed in when using the xoauth_requestor_id query string parameter or when passing in an OAuth token.
  • An integer value: MySpace IDs are integers. For example, Tom is 6221. 6221 is a valid integer value.
  • myspace.com.person.[integer value]: PersonIDs also support type identifier prepended to the integer value. Tom's value is myspace.com.person.6221.

{albumId}

The albumId indicates which single album from the group identified by {selector} should be returned. This is used when an application wants to display a single album it created. Valid values are:

  • An integer value: Gives the integer identifier of the album.
  • myspace.com.album.[integer value]

Notes

  • The following are default fields and are always returned when fetching albums
    • id
    • caption
    • thumbnailUrl
    • location
  • The following fields are not supported by MySpace in OpenSocial 0.9
    • description
    • mediaMimeType
  • The following are MySpace extended fields
    • msPrivacyLevel, a string indicating album’s privacy level. Possible values are
      • me - Album is private.
      • friendsonly - Album is visible to friends.
      • everyone - Album is visible to everyone.
  • Album endpoints only support @self requests.
  • By default, albums will be created as public (msPrivacyLevel = everyone).
  • Endpoints will return empty album(s) only if the person is the viewer.
  • The response URI for create/update endpoints is the actual URI for that album resource.
  • There is no need to set ownerId (for create/update) and albumId (for update) in Album objects. The endpoints will take the values from the URI. If provided, the endpoint will make sure they are the same otherwise, it’ll return an error.
  • The following fields can be set for an album creation request: caption, location,msPrivacyLevel. The caption cannot be set as empty or null.
  • The following fields can be modified during an album update request: caption, location. If any of these fields are not set during the update, it will assume previous values.
  • During an album create/update request, for location, it will give the formatted field precedence, if not provided it will look for other fields and combine them in following order: streetAddress, locality, region, postalCode, country. Other fileds of the Address object are not supported for location. Use formatted field instead.
  • The following table lists of the various permissions and what they stand for.
Permission Permission on App Settings page Notes
Viewer_access_to_public_videos_photos App gets this permission automatically if app is installed. It will grant access to user’s public albums.
Viewer_access_to_private_videos_photos View my private photos & videos It will grant access to user’s private albums. [me and friendsonly]
Viewer_add_photos_to_albums Allow this app to upload photos. It will grant access to create albums.

Note – the app can only request permissions for the viewer.

Filtering Results

OpenSocial supports a set of standard query parameters for filtering data. Depending on the endpoint, different sets of query parameters are supported with different, well known values. This section details how MySpace supports the standard query parameters for Albums.

  • count: Supported.
  • fields: Supported. Currently handles the following field names: (bold are always returned)
    • id
    • thumbnailUrl
    • caption (use in place of title)
    • title (is not supported use caption instead)
    • mediaItemCount
    • ownerId
    • mediaType
    • location
    • @all: A special value that tells the REST endpoint to send back all fields for the Album.
    • msPrivacyLevel: MySpace specific field. May be one of the following values:
      • me: Album is private.
      • friendsonly: Album is visible to friends.
      • everyone: Album is visible to everyone.
  • filterBy: Not supported.
  • filterOp: Not supported.
  • filterValue: Not supported.
  • format: Determines the format of the response. We currently support json and xml.
  • networkDistance: Not supported.
  • sortBy: Not supported.
  • sortOrder: Not supported.
  • startIndex: Indicates the index of the first item to retrieve from the query set.
  • updatedSince: Not supported.

Examples

Like all OpenSocial endpoints, the albums endpoint requires OAuth parameters in all requests. The examples on this page do not show the OAuth parameters.

Retrieve all supported fields

Request: GET http://opensocial.myspace.com/roa/09/albums/@supportedFields

Response: 

["id","mediaItemCount","mediaType","ownerId","caption","thumbnailUrl","location","msPrivacyLevel"]

Request: GET http://opensocial.myspace.com/roa/09/albums/@supportedFields?format=xml

Response: 

<ArrayOfstring 
  xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays" 
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <string>id</string>
  <string>mediaItemCount</string>
  <string>mediaType</string>
  <string>ownerId</string>
  <string>caption</string>
  <string>thumbnailUrl</string>
  <string>location</string>
  <string>msPrivacyLevel</string>
</ArrayOfstring>

PHP Sample

/**
 * Get supported fields.
 * @using osapi PHP SDK 
 */
 
require_once "osapi/osapi.php";
 
$appKey = '<app key>';
$appSecret = '<app secret>';
$userId = '<userId>';
 
$osapi = new osapi(new osapiMySpaceProvider(), new osapiOAuth2Legged($appKey, $appSecret, $userId));
$batch = $osapi->newBatch();
 
// The second option in the $batch->add() assigns a request Id.
$batch->add($osapi->albums->getSupportedFields(), 'supported_fields');
 
// Send all batched commands
$result = $batch->execute();
 
// Demonstrate iterating over a response set, checking for an error & working with the result data. 
foreach ($result as $key => $result_item) {
    if ($result_item instanceof osapiError) {
      echo "<h2>There was a <em>".$result_item->getErrorCode()."</em> error with the <em>$key</em> request:</h2>";
      echo "<pre>".htmlentities($result_item->getErrorMessage())."</pre>";
    } else {
      echo "<h2>Response for the <em>$key</em> request:</h2>";
      echo "<pre>".htmlentities(print_r($result_item, True))."</pre>";
    }
}

Retrieve albums

Request: GET http://opensocial.myspace.com/roa/09/albums/@me/@self

Response: 

{"entry":[
  {"album": 
    {"caption":"Test Security",
     "id":"myspace.com.album.1224563",
     "thumbnailUrl":"http:\/\/c2.ac-images.myspacecdn.com\/images02\/16\/m_46e99190a67b4cedaecc4d9889c8ea25.jpg"
    }
  }],
  "itemsPerPage":1,
  "startIndex":1,
  "totalResults":2}

Request: GET http://opensocial.myspace.com/roa/09/albums/@me/@self?format=xml

Response: 

<response xmlns="http://ns.opensocial.org/2008/opensocial" 
          xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <entry>
    <entry>
      <album>
        <caption>Test Security</caption>
        <id>myspace.com.album.1224563</id>
        <mediaItemCount>1</mediaItemCount>
        <mediaType>IMAGE</mediaType>
        <ownerId>398672205</ownerId>
        <thumbnailUrl>http://c2.ac-images.myspacecdn.com/images02/16/m_46e99190a67b4cedaecc4d9889c8ea25.jpg</thumbnailUrl>
      </album>
    </entry>
  </entry>
  <itemsPerPage>1</itemsPerPage>
  <startIndex>1</startIndex>
  <totalResults>2</totalResults>
</response>

PHP Sample

/**
 * Retrieve a list of albums for viewer
 * @using osapi PHP SDK 
 */
 
require_once "osapi/osapi.php";
 
$appKey = '<app key>';
$appSecret = '<app secret>';
$userId = '<userId>';
 
$osapi = new osapi(new osapiMySpaceProvider(), new osapiOAuth2Legged($appKey, $appSecret, $userId));
$batch = $osapi->newBatch();
 
 
// Set Parameters (get 2 albums, and all fields)
$user_params = array(
    'userId' => $userId, 
    'groupId' => '@self', 
    'count' => 2,
    'fields'=>'@all'
);
 
// The second option in the $batch->add() assigns a request Id.
$batch->add($osapi->albums->get($user_params), 'get_albums');
 
// Send all batched commands
$result = $batch->execute();
 
// Demonstrate iterating over a response set, checking for an error & working with the result data. 
foreach ($result as $key => $result_item) {
    if ($result_item instanceof osapiError) {
      echo "<h2>There was a <em>".$result_item->getErrorCode()."</em> error with the <em>$key</em> request:</h2>";
      echo "<pre>".htmlentities($result_item->getErrorMessage())."</pre>";
    } else {
      echo "<h2>Response for the <em>$key</em> request:</h2>";
      echo "<pre>".htmlentities(print_r($result_item, True))."</pre>";
    }
}

Add albums

Request: PUT http://opensocial.myspace.com/roa/09/albums/@me/@self 

{ "caption":"This is another test",
  "mediaItemCount":0}

Response: 

{"statusLink": "http:\/\/opensocial.myspace.com\/roa\/09\/albums\/myspace.com.person.398672205\/@self\/myspace.com.album.1689899"}

PHP Sample

/**
 * Create an album for viewer
 * @using osapi PHP SDK
 */
 
require_once "osapi/osapi.php";
 
$appKey = '<app key>';
$appSecret = '<app secret>';
$userId = '<userId>';
 
$osapi = new osapi(new osapiMySpaceProvider(), new osapiOAuth2Legged($appKey, $appSecret, $userId));
$batch = $osapi->newBatch();
 
$album = new osapiAlbum();
$album->setFields('caption', 'new album caption');
 
$user_params = array(
    'userId' => '@me', 
    'groupId' => '@self', 
    'album' => $album
);
 
// The second option in the $batch->add() assigns a request Id.
$batch->add($osapi->albums->create($user_params), 'create_album');
 
// Send all batched commands
$result = $batch->execute();
 
// Demonstrate iterating over a response set, checking for an error & working with the result data. 
foreach ($result as $key => $result_item) {
    if ($result_item instanceof osapiError) {
      echo "<h2>There was a <em>".$result_item->getErrorCode()."</em> error with the <em>$key</em> request:</h2>";
      echo "<pre>".htmlentities($result_item->getErrorMessage())."</pre>";
    } else {
      echo "<h2>Response for the <em>$key</em> request:</h2>";
      echo "<pre>".htmlentities(print_r($result_item, True))."</pre>";
    }
}

Update album

Request: POST http://opensocial.myspace.com/roa/09/albums/@me/@self/myspace.com.album.1689899 

{ "caption":"This is an update test",
  "id": "myspace.com.album.1689899",
  "mediaItemCount":0}

Response: 

{"statusLink": "http:\/\/opensocial.myspace.com\/roa\/09\/albums\/myspace.com.person.398672205\/@self\/myspace.com.album.1689899"}

PHP Sample

/**
 * Update an album for viewer
 * @using osapi PHP SDK
 */
 
require_once "osapi/osapi.php";
 
$appKey = '<app key>';
$appSecret = '<app secret>';
$userId = '<userId>';
 
$osapi = new osapi(new osapiMySpaceProvider(), new osapiOAuth2Legged($appKey, $appSecret, $userId));
$batch = $osapi->newBatch();
 
$album = new osapiAlbum();
$album->setFields('caption', 'updated album caption');
$user_params = array(
    'userId' => '@me', 
    'groupId' => '@self', 
    'album' => $album,
    'albumId'=>'myspace.com.album.3018169'
);
 
// The second option in the $batch->add() assigns a request Id.
$batch->add($osapi->albums->update($user_params), 'update_album');
 
// Send all batched commands
$result = $batch->execute();
 
// Demonstrate iterating over a response set, checking for an error & working with the result data. 
foreach ($result as $key => $result_item) {
    if ($result_item instanceof osapiError) {
      echo "<h2>There was a <em>".$result_item->getErrorCode()."</em> error with the <em>$key</em> request:</h2>";
      echo "<pre>".htmlentities($result_item->getErrorMessage())."</pre>";
    } else {
      echo "<h2>Response for the <em>$key</em> request:</h2>";
      echo "<pre>".htmlentities(print_r($result_item, True))."</pre>";
    }
}
Retrieved from "http://wiki.developer.myspace.com/index.php?title=OpenSocial_v0.9_Albums"