PeopleAggregator API: method peopleaggregator.getAlbums

Arguments | Return value | REST (XML) example | REST (JSON) example | XML-RPC example

Method: peopleaggregator.getAlbums

Retrieve all albums that a given user, or an anonymous viewer, can access.
User documentation for peopleaggregator.getAlbums on the PeopleAggregator wiki

Arguments (see also Authentication)

If calling by XML-RPC, note that this method takes a single struct as input, with the following keys:

authToken

Type: string
If present, an authentication token for the user to act as.
Example: as9d867f234o7asdf:928734982734987234:298374982734987234

context

Type: string
'user:123' to return all visible personal albums for user 123, or if an authToken is provided: 'user' to return all your personal albums, 'group' to return your groups, or 'all' to return your albums *and* groups
Example: user
Default: user

Return value (see also Exceptions)

Type: hash

Attributes:

success

Type: boolean
true if the file was successfully received and saved, or false if an error occurred.
Example: True

albums

Type: array

Content of each item:

item

Type: hash

Attributes:

id

Type: string
Album ID
Example: user:26:album:42

access

Type: enum
Access level the given user (or anonymous viewer) has to this album. 'write' means you can publish to the album, whereas 'read' means you can view the album.
Allowed values: read, write
Example: read

title

Type: string
Album name
Example: My family photos

created

Type: string
When the message was created
Example: (FIXME: some sort of standard date value?)

type

Type: array
Content types allowed. Personal albums only allow one content type, but group albums can hold multiple content types. (Actually, behind the scenes, your content is split into multiple albums. We might give these all different IDs at some point - not sure yet.)

Content of each item:

item

Type: enum
Content type allowed
Allowed values: image, audio, video
Example: image

Example REST (XML) request

Request

GET /api/xml/peopleaggregator/getAlbums?authToken=as9d867f234o7asdf%3A928734982734987234%3A298374982734987234&context=user HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 607

<response>
 <albums>
  <item>
   <access>read</access>
   <created>(FIXME: some sort of standard date value?)</created>
   <type>
    <item>image</item>
   </type>
   <id>user:26:album:42</id>
   <title>My family photos</title>
  </item>
 </albums>
 <success>true</success>
</response>

Example REST (JSON) request

Request

GET /api/json/peopleaggregator/getAlbums?authToken=as9d867f234o7asdf%3A928734982734987234%3A298374982734987234&context=user HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/x-javascript
Content-Length: 180

{"albums": [{"access": "read", "created": "(FIXME: some sort of standard date value?)", "type": ["image"], "id": "user:26:album:42", "title": "My family photos"}], "success": true}

Example XML-RPC call

Request

POST /api/xmlrpc HTTP/1.1
Content-Type: text/xml
Content-Length: 1026

<?xml version='1.0'?>
 <methodCall>
  <methodName>peopleaggregator.getAlbums</methodName>
  <params>
   <param>
    <value><struct>
     <member>
      <name>authToken</name>
      <value><string>as9d867f234o7asdf:928734982734987234:298374982734987234</string></value>
     </member>
     <member>
      <name>context</name>
      <value><string>user</string></value>
     </member>
    </struct></value>
   </param>
  </params>
 </methodCall>
 

Response

HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 3089

<?xml version='1.0'?>
 <methodResponse>
  <params>
   <param>
    <value><struct>
     <member>
      <name>albums</name>
      <value><array><data>
       <value><struct>
        <member>
         <name>access</name>
         <value><string>read</string></value>
        </member>
        <member>
         <name>created</name>
         <value><string>(FIXME: some sort of standard date value?)</string></value>
        </member>
        <member>
         <name>type</name>
         <value><array><data>
          <value><string>image</string></value>
         </data></array></value>
        </member>
        <member>
         <name>id</name>
         <value><string>user:26:album:42</string></value>
        </member>
        <member>
         <name>title</name>
         <value><string>My family photos</string></value>
        </member>
       </struct></value>
      </data></array></value>
     </member>
     <member>
      <name>success</name>
      <value><boolean>1</boolean></value>
     </member>
    </struct></value>
   </param>
  </params>
 </methodResponse>