PeopleAggregator API: method peopleaggregator.newFile

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

Method: peopleaggregator.newFile

Creates a new media object on the server, either by uploading a file or by supplying a URL. (FIXME - upload probably only works in XML-RPC mode at the moment. REST *might* work, but it's not guaranteed and not tested.) This lets you upload media (image, audio, video) files, i.e. it presents an API to the upload function in media_gallery.php. Either the 'url' parameter, or both the 'filename' and 'data' parameters, must be supplied.
User documentation for peopleaggregator.newFile 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
An authentication token
Example: as9d867f234o7asdf:928734982734987234:298374982734987234

filename

Type: string
Filename of uploaded file
Example: my-picture.jpg

url

Type: string
URL to use instead of uploaded file (if no filename and data are provided)
Example: http://example.org/my-remote-picture.jpg

type

Type: enum
File class
Allowed values: image, audio, video
Example: image
Default: image

title

Type: string
Title to use when displaying the file
Example: A picture of me.

content

Type: string
Description of the file
Example: Picture of me crossing a pond at Blue Skies, Kaiapoi, New Zealand. Taken by my girlfriend on 11 May 2006.

tags

Type: string
Comma-separated list of tags
Example: one, two, three
Default:

context

Type: string
ID of the album (retrieved from peopleaggregator.getAlbums or peopleaggregator.newAlbum) in which to place this file.
Example: album:52

access

Type: enum
Who can see this file
Allowed values: nobody, everybody, relations
Example: everybody
Default: nobody

data

Type: binary
File contents. (XML-RPC: send as a base64 object.)

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

id

Type: string
ID of the newly uploaded file
Example: file:123

url

Type: string
URL of the newly uploaded file
Example: http://peopleaggregator.org/files/my-picture.jpg

Example REST (XML) request

Request

POST /api/xml/peopleaggregator/newFile HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 387

authToken=as9d867f234o7asdf%3A928734982734987234%3A298374982734987234&content=Picture+of+me+crossing+a+pond+at+Blue+Skies%2C+Kaiapoi%2C+New+Zealand.++Taken+by+my+girlfriend+on+11+May+2006.&title=A+picture+of+me.&url=http%3A%2F%2Fexample.org%2Fmy-remote-picture.jpg&type=image&tags=one%2C+two%2C+three&filename=my-picture.jpg&access=everybody&context=album%3A52&data=binary+data+goes+here

Response

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

<response>
 <url>http://peopleaggregator.org/files/my-picture.jpg</url>
 <id>file:123</id>
 <success>true</success>
</response>

Example REST (JSON) request

Request

POST /api/json/peopleaggregator/newFile HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 387

authToken=as9d867f234o7asdf%3A928734982734987234%3A298374982734987234&content=Picture+of+me+crossing+a+pond+at+Blue+Skies%2C+Kaiapoi%2C+New+Zealand.++Taken+by+my+girlfriend+on+11+May+2006.&title=A+picture+of+me.&url=http%3A%2F%2Fexample.org%2Fmy-remote-picture.jpg&type=image&tags=one%2C+two%2C+three&filename=my-picture.jpg&access=everybody&context=album%3A52&data=binary+data+goes+here

Response

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

{"url": "http://peopleaggregator.org/files/my-picture.jpg", "id": "file:123", "success": true}

Example XML-RPC call

Request

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

<?xml version='1.0'?>
 <methodCall>
  <methodName>peopleaggregator.newFile</methodName>
  <params>
   <param>
    <value><struct>
     <member>
      <name>authToken</name>
      <value><string>as9d867f234o7asdf:928734982734987234:298374982734987234</string></value>
     </member>
     <member>
      <name>access</name>
      <value><string>everybody</string></value>
     </member>
     <member>
      <name>title</name>
      <value><string>A picture of me.</string></value>
     </member>
     <member>
      <name>url</name>
      <value><string>http://example.org/my-remote-picture.jpg</string></value>
     </member>
     <member>
      <name>data</name>
      <value><base64>
       YmluYXJ5IGRhdGEgZ29lcyBoZXJl
      </base64></value>
     </member>
     <member>
      <name>tags</name>
      <value><string>one, two, three</string></value>
     </member>
     <member>
      <name>filename</name>
      <value><string>my-picture.jpg</string></value>
     </member>
     <member>
      <name>content</name>
      <value><string>Picture of me crossing a pond at Blue Skies, Kaiapoi, New Zealand. Taken by my girlfriend on 11 May 2006.</string></value>
     </member>
     <member>
      <name>context</name>
      <value><string>album:52</string></value>
     </member>
     <member>
      <name>type</name>
      <value><string>image</string></value>
     </member>
    </struct></value>
   </param>
  </params>
 </methodCall>
 

Response

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

<?xml version='1.0'?>
 <methodResponse>
  <params>
   <param>
    <value><struct>
     <member>
      <name>url</name>
      <value><string>http://peopleaggregator.org/files/my-picture.jpg</string></value>
     </member>
     <member>
      <name>id</name>
      <value><string>file:123</string></value>
     </member>
     <member>
      <name>success</name>
      <value><boolean>1</boolean></value>
     </member>
    </struct></value>
   </param>
  </params>
 </methodResponse>