Developer
This is a partial listing of the 1.2 Plum REST api. We will be improving this documentation over the next few weeks as well as broadening it to include currently undocumented methods. All methods take a version number; the current version number is 1.2.
Parameters may be sent either url encoded, form encoded, or as an xml document with the following format:
<plum>
<parameter name=parameter name>parameter value</property>
...
</plum>
Parameter values are assumed to be strings unless the parameter type is set to "xml":
<parameter name=parameter name type="xml">parameter value</property>
We suggest complex descriptions be sent either form encoded or as XML CDATA. We currently support return formats of XML (default), rss and json. We will be supporting json as in input format in the near future. The listen.x method provides support for importing RSS feeds as collections into Plum.
collection/getCollectionsForUser.x
Gets the list of collections (topics) for a given user
Required
- v API version number.
Optional
- user_id The Plum identifier for the user whose collections are to be returned. You must supply EITHER user_id OR puser_id.
- puser_id The partner's identifier for the user whose collections are to be returned. The user must have an existing account with Plum. You must supply EITHER user_id OR puser_id. If you specify the puser_id you must also sign the request and include your partner id, as described in the partner integration guide.
Example return document:
collection/getSharedCollections.x
Gets the list of collections to which both the logged in user and the user specified have write rights.
Required
- v API version number.
Optional
- user_id The Plum identifier for the user whose collections are to be returned. You must supply EITHER user_id OR puser_id.
- puser_id The partner's identifier for the user whose collections are to be returned. The user must have an existing account with Plum. You must supply EITHER user_id OR puser_id. If you specify the puser_id you must also sign the request and include your partner id, as described in the partner integration guide.
Example return document:
addCollection.x
Creates and adds a new collection. Requires a logged in session.
Required
- v API version number.
- element_id The parent for the new collection. This may be either a user or another collection.
- name The name for the new collection.
Optional
- description The description for the new collection.
- tag The tags for the new collection. Separate multiple tags with commas
- template_name Name of the template to apply to thiscollection. Valid values are
Example return document:
addItem.x
Adds a new item to plum.
Required
- v API version number.
- element_id The collection to which to add this item. Items can only be added to collections.
- name Name for the new collection
Optional
- from Element id of element to be copied before applying the new values
- description The description for the new item
- tag Tags for the new item. Separate multiple tags with commas
- url Url of the bookmark for this item
- page_value Cached page.
- image_xml plum media element describing the element. media elements are returned by the plum image search apis
- image_url source url for the image
- image_file Image file
- template_name Name of the template to apply to this element. Valid values are
- prop-emailBody Email body
- prop-emailSubject Email subject
Note that any property can be added to an item by passing the parameter prop-<propertyname>, for example prop-map=http://mapserver.example.com?city=lincoln&state=ma Properties are always returned in the xml document in property tags.
Example return document:
getElement.x
Gets and element. By default getElement also fetches the names and paths of all the children. To get just the element itself specify headerOnly=true. To get the full details on all children use getElementFull.x
Required
- element_id The element id to fetch
- v API version number.
- user_id The logged in user id, or -1 for the public view of the element
Optional
- headerOnly if "true" does not return any information about children
- format Use format=rss to get result document in RSS format.
Example return document:
getElementFull.x
Gets an element and all children
Required
- element_id The element id to fetch
- v API version number.
- user_id The logged in user id, or -1 for the public view of the element
Example return document:
listen.x
Adds a feed to a collection
Required
- url The url of the feed
- v API version number.
Example return document:
login.x
Login into plum.
Required
- v API version number.
- username The user name
- password MD5 hash of the user's password
Example return document:
setProperty.x
Sets a property value. Send an empty value to remove a property.
Required
- v API version number.
- prop-<propertyname>
Example return document:
JSON Support
To get your api results in JSON format include the parameter output_format=json in your parameter list. For example:
http://www.plum.com/getElement.x?v=1.1&user_id=-1&element_id=157442&output_format=json
We support the callback parameter (callback=function); if you specify the callback parameter the JSON output text will be wrapped in a function call. For example:
http://www.plum.com/getElement.x?v=1.1&user_id=-1&element_id=157442&callback=myfunc&output_format=json
will return results as myfunc(...json output...);
RSS Support
To get your api as an RSS feed include the parameter output_format=rss in your parameter list. For example:
http://www.plum.com/getElement.x?v=1.1&user_id=-1&element_id=157442&output_format=rss