All API requests are done using a RESTful format. Simply GET or POST to the appropriate endpoint adding the proper name value pairs as documented here. Data is returned as either XML or JSON. By default data is returned as XML. To enable JSON simply append the extension ".json" to your request. The domain of your api request should always include the user you wish to authenticate for.
If you are authenticating via OAuth, the password parameter is not required, however the user must allow your application to access their data. See the Multiply OAuth documentation for details.
Support
Official support, examples and code libraries can be found at the api group site, MultiplyAPI.
Authentication
Basic (base64 encode uname:password in HTTP Authentication Header)
as RESTful arguments ($uid gleaned from domain, password=$password in query string)
Authentication failures will be
returned as 401 HTTP_UNAUTHORIZED errors.
Developer Key
All API requests must supply a developer key, which is tied to a particular Multiply user. (Usually the developer of the application.) To retrieve your developer key, visit http://multiply.com/apis/developer-key while logged in as the user whose developer key you would like to retrieve.
Each request should send the application's key as api_key=$developer_key in the query string
Returning data
Data will be formatted as xml or json
according to the extension of the query. Additionally json
formatted requests can include a “callback=$callback” in the
query string to have the data returned as a javascript function with
the json string as its argument.
Invalid format requests will be
returned with an HTTP_NOT_ACCEPTABLE error.
Errors
Any errors will be reported back to the client with the appropriate non-200 (HTTP_OK) status code as well as a short error message in the body of the document. Provided a valid format is requested, the error message will be encapsulated using xml or json. Due to a limitation with the apache web server the Content-type header associated with error messsages will always be 'text/html'. The actual data returned will have the requested format, however, so api clients should simply ignore this header.
curl -i 'http://foonasty.multiply.com/api/mailbox.xml?password=badpass'
HTTP/1.x 403 Forbidden
Date: Tue, 04 Aug 2009 20:28:31 GMT
Server: Apache/1.3.29 (Unix) mod_perl/1.29
Connection: close
Transfer-Encoding: chunked
Content-Type: text/html; charset=iso-8859-1
<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://multiply.com/api/0.1">
<error>username and password do not match</error>
</response>
curl 'http://foonasty.multiply.com/api/mailbox.json?password=badpass'
{"error":"username and password do not match"}
Requests to /api/inbox will return
the the first 20 entries of a user's inbox using the user's default filter (as
defined by the user on the web site). The type of content returned
by /api/inbox may be modified using a “filter” argument. A
list of valid filters for a given user may be collected by requesting
/api/filters.
Advanced filtering options
Additionaly, mailbox content may be
filtered by using any of these filter building blocks:
type limit entries by content type. Valid values are journal, photos, video, music, recipes, reviews, market, calendar, notes, guestbook, links or pms.
sort leave undefined for default sort. Set to "created" for reverse cronological order.
group return only group posts. Set to "all" for all groups or a comma delimited list of groups
fof set to 1 to return posts from friends of friends
undread set to 1 to return only unread posts
replied set to 1 to return only posts to which the user has replied
Paging through results
Requests to /inbox will return the
first 25 entries in the inbox that match a given filter as well as
a total_matching_filter field that documents the total number of
messages available with that filter. To get the next 25 messages,
set the start argument in the api request to 26, 51 and so on.
Returned data
Inboxes data is contains two top level nodes:
total_matching_filter and messages. The total_matching_filter node
has a sinlge interger. The messages node contains up to 25
individual message blocks.
Returns a list of email filters, each filter having two data nodes: name
and label. Use the name node as an argument for the filter paramater
when making inbox querries.
Returned data
Inboxes data is contains two top level nodes:
total_matching_filter and messages. The total_matching_filter node
has a sinlge interger. The messages node contains up to 25
individual message blocks.
Returns profile information for $user_id. Profile content is actualy dyamic, in that some users
choose to share information with other users based on their
relationship status.
Posting is accomplished by calling /api/post and sending the appropriate
parameters for a given content type. If the content type supports
attachements (such as photos, videos, cover shots for reviews, etc.),
then files may be attached using the multipart/form-data posting method (similar to
the upload box used in a web form).
Content type specific paramers are listed in sub-sections below. All
content types support the following parameters:
/api/post?type=photos
A successful photo post will return an HTTP status code of 200 as well as the album's item_key.
A successful quicknote post will return an HTTP status code of 200 as well as the item_key. Please note: The entirety of a quicknote is contained in the "subject" portion. The "body" field is ignored.
This method returns a listing of items
for a specific item type. The type parameter must be present for a
valid read request.
Read will return the first 100 items in reverse cronological order of
their creation dates. The returned data will also include a total number of
listings available. If there are more then 100 available the next 100
can be requested by setting the "start" parameter to 101, then 201, etc.
Valid paramters to read are:
type - one of journal, photos, video, music, recipes, reviews, market, calendar, notes, guestbook, links or pms
item_key - the unique identier for a given item. item_keys are labeled as such in lists returned from reads or inbox queries.
start - integer; return reads starting at that offset.
This method returns a detailed description of a specific item. Item_key or type must be present for a valid read request. All item_key requests will return the fields listed below.
Depending on the item type, there will be additional fields.
photos
Photos will have an additional "photos" node that will contain an array of photo hashes. Each hash will have the following fields: