API:v1r1:thingies controller
From MixxHelp
Contents |
Thingies Service
/services/v1r1/thingies/<action>
The thingies service, which is responsible for retrieving photos, videos, and stories, as well as accepting user comments and submissions, is the most full-featured service in the Mixx API. It makes sense, since the data standing behind it is the lifeblood of what makes Mixx what it is. This service makes simple calls simple, but also offers a multi-step submission process that is somewhat more complex. When retrieving such items, even when using another service like the tags service, there is an optional parameter "abbr=1" that, when passed, abbreviates the output of each item somewhat. The example below do not use this parameter, in order to show the full output surrounding an item.
A Word on Categories
When retrieving items, you can choose to retrieve those which are in a given category. Since the Mixx application treats categories and tags the same (because they're actually the same thing in the data), you'll use the tags service to accomplish this. Head on over to the relevant section for instructions.
popular
Retrieves currently popular items.
Optional parameters
- type=[stories|photos|videos], defaults to return all three types
GET http://api.mixx.com/services/v1r1/thingies/popular?api_key=YOUR_API_KEY <?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok" api_version="v1r1"> <thingies> <thingy type="story" created_at="Mon Apr 28 18:24:54 UTC 2008" id="159027"> <title>McCain rejects 'big government' takeover of health care - CNN.com</title> <permalink>http://www.mixx.com/stories/159027/mccain_rejects_big_government_takeover_of_health_care_cnn_com</permalink> <target_url>http://www.cnn.com/2008/POLITICS/04/28/mccain/index.html</target_url> <description>Sen. John McCain on Monday rejected a "big government" takeover of the health care system, saying he wants to empower families to make more medical decisions.</description> <comment_count>0</comment_count> <vote_count>1</vote_count> <submitter name="iworedettos"/> </thingy> <thingy type="photo" created_at="Wed Mar 05 13:51:09 UTC 2008" id="134796"> <title>in ur base</title> <permalink>http://www.mixx.com/photos/134796/in_ur_base</permalink> <target_url>http://www.icanhasforce.com/2008/03/04/caption-this-4/</target_url> <description>Andy posted a caption for this pic of jawas takin r2. Everybody posts and votes on the captions and the winner gets his posted and credit.</description> <thumbnail type="image/jpeg">http://images.mixx.com/images/photo_thumbnails/d47dec3c182fa743b7b4007b1d39713d9d7c098d_96s.jpg</thumbnail> <comment_count>1</comment_count> <vote_count>3</vote_count> <media_url>http://www.icanhasforce.com/wp-content/uploads/2008/03/star-wars-jawas-stealin-r2d2.jpg</media_url> <submitter name="anderl"/> </thingy> </thingies> </rsp>
show
Shows the information about a given item.
Required parameters
- One of the following:
- id, the Mixx ID of the specific item
- url, the URL to the external page the item refers to (encoded)
Optional parameters
- comments=1, will return comments associated with the item
- tags=1, will show a list of tags applied to the item
GET http://api.mixx.com/services/v1r1/thingies/show?url=http%3A%2F%2Fwww.icanhasforce.com%2F2008%2F03%2F04%2Fcaption-this-4 (Note that the api_key parameter was left off of the above URL for brevity, but it is still required) <?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok" api_version="v1r1"> <thingies> <thingy type="photo" created_at="Wed Mar 05 13:51:09 UTC 2008" id="134796"> <title>in ur base</title> <permalink>http://www.mixx.com/photos/134796/in_ur_base</permalink> <target_url>http://www.icanhasforce.com/2008/03/04/caption-this-4/</target_url> <description>Andy posted a caption for this pic of jawas takin r2. Everybody posts and votes on the captions and the winner gets his posted and credit.</description> <thumbnail type="image/jpeg">http://74.205.85.169:7500/images/photo_thumbnails/d47dec3c182fa743b7b4007b1d39713d9d7c098d_96s.jpg</thumbnail> <comment_count>1</comment_count> <vote_count>3</vote_count> <media_url>http://www.icanhasforce.com/wp-content/uploads/2008/03/star-wars-jawas-stealin-r2d2.jpg</media_url> <submitter name="anderl"/> </thingy> </thingies> </rsp>
Submitting Content
The thingies service makes it possible to submit photos, videos, and stories to Mixx, as well as to post comments to existing items. All of these actions require a valid auth_token, and, of course, api_key and api_sig. In the interests of brevity, we will not include those parameters in our example URLs below, but the API will not allow submission of data without them. Submitting an item (other than a comment) is a two-step process:
presubmit
JSON is not supported by this action.
You begin by POSTing to the presubmit service an XML document giving information about the item you wish to submit. Items not marked as optional below are required.
<? xml version='1.0' charset='UTF-8' ?> <thingy> <type>photo</type><!-- Can be photo, video, or story --> <page_url>http://icanhascheezburger.com/</page_url> <title>Cheezburgers!</title><!-- optional --> <description>Cats n stuff</description><!-- optional --> <tags>cats,lolcats,cheezburgers</tags><!-- optional --> </thingy>
The item will be checked to see if it is a duplicate of any other items. If a duplicate is found, the response will contain 'dupes' as the single child of the 'rsp' element, with a thingy as the sole child element. The item will also be checked for a number of error conditions, so be sure to check the 'stat' attribute of the rsp root. If you were submitting a photo and multiple images were found at page_url, you'll be presented with a collection of 'image' elements under a 'candidate_images' parent, each with a 'media_url' attribute that you can present to your user for selection. If all goes well, you'll be presented with a partially populated thingy element, the data from which you'll use in the next step.
submit
JSON is not supported by this action.
Step two of the submit process is almost identical to step one (presubmit), but the output can be different. In step two you're posting essentially the same XML you did in step one, except that you may make use of an auto-generated title, description, and/or media_url that came out of step one. The results are also largely similar; if there are potential duplicates (in presubmit we only check for exact duplicates), you'll get back a 'dupes' element with multiple thingy entries. Otherwise you'll get a simple thingy response that contains the data of the item that has been added to the system.
comment
JSON is not supported by this action.
Adding a comment to an item is simple. You'll need to pass the id of the item to comment on, and all the usual parameters that are required when accessing functionality that requires an authenticated user. You simply post XML in the following format:
<? xml version='1.0' charset='UTF-8' ?> <comment> <body>This is the text of an informative and witty comment.</body> </comment>
The response simply gives back the ID of the new comment.
