ShortReviews/LongReviews REST API v1.0



This documentation will always be available in its latest form at http://api.rvws.net

An example site built with this site is available at http://toppirate.com, and the source for this site can be downloaded from http://api.rvws.net/files/tp_src.zip

Requests

GET POST DELETE PUT
If the library you are using does not support DELETE requests, use a POST request with the parameter _method=DELETE

All requests are required to have the following parameters:
userid
key
both of these can be found on your account settings page. All requests are rate limited by user, as specified on each method

Example request:
http://api.rvws.net/1/review.json?userid=1&key=098f6bcd4621d373cade4e832627b4f6&id=6134

Requests can be in either json or xml format

Return Codes

200 - successful
400 - invalid request, probably missing required parameters
401 - outdated or incorrect userid/key
403 - probably rate limited
404 - failed request, item did not exist
406 - this method does not support the request type you provided (e.g. GET vs POST)


Error Returns:
code - the http error code
message - description of the error
wait - how many seconds to wait before retrying this request, only included on rate limit errors

{"error":{"code":403,"message":"Rate limited, no more than one request per second","wait":3}}


API Methods

Retrieve pages of reviews
Retrieve a review
Submit a review
Delete a review

Retrieve all items on a list
Add item to a list
Remove item from a list

Retrieve all your lists
Add a new list
Rename a list
Delete a list

Find item ID
Add a new item

GET /1/review.format

Description: Retrieves your review on a specified item
Parameters:
id - the ID of the item you reviewed
extended - optional, set this argument to 1 if you want the data to include the movie title and cover art

Returns:
{"review":{"id":"1780","movie":12944,"rating":"2.0","type":"short","text":"Decent acting, but the story felt a bit disjointed. Some parts were interesting - others were pretty slow - but I would never describe it as exciting or suspenseful. If the cast had been worse this would have been a <i>terrible</i> film"}}



POST or PUT /1/review.format

Description: Submits a review, or overwrites if one exists already
Parameters:
id - the ID of the item you are reviewing
rating - the rating from 0-5 in increments of .5
text - the review


DELETE /1/review.format

Description: Deletes your review on a specified item
Parameters:
id - the ID of the item you reviewed




GET /1/reviews.format

Description: Retrieves pages of your reviews
Parameters:
sort - the ordering to use - dateasc, datedesc, rateasc, ratedesc
type - optional, media type - film, music, book, game
page - optional, (zero based) returns 15 reviews per page
extended - optional, set this argument to 1 if you want the data to include the movie title and cover art

Returns:
{"reviews":[{"id":"1842","movie":"182105","rating":"2.5","type":"short","text":"Brooke Nevin and Jimmi Simpson are great, but replacing Nicole Steinwedell with Serinda Swan after one episode was a mistake as well as an odd script choice. The cast is slowly getting better each episode."},{"id":"1830","movie":"182093","rating":"4.0","type":"short","text":"Foreign with Subtitles. Reminds me of a 20th century Lara Croft. Thoroughly entertaining, but the police scenes were <a href=\"/review/146332-the-pink-panther/\" target=\"_blank\">The Pink Panther</a> quality bumbling, and not quite as funny as intended. Hopefully they'll make more in the series."},{"id":"1829","movie":"181241","rating":"0.5","type":"short","text":"This had potential to be suspenseful in the beginning, but then the terrible gunfights began. Unlimited ammo, trading shots and never hitting anything for minutes on end. The priest/church part of the story was an unnecessary plot device as well."},{"id":"1827","movie":"182092","rating":"3.0","type":"short","text":"Good casting, especially Vera Farmiga - she was perfect for that role. The ending could have been a bit more shocking/artistic if they had just cut it off, but it probably wouldn't have played as well with audiences."},{"id":"1826","movie":"182091","rating":"3.5","type":"short","text":"More action than your typical lawyer film. Good cast and decent script - a bit predictable in parts but still entertaining to watch."}],"count":988}




GET /1/search.format

Description: Find the ID of an item
Parameters:
type - film, music, book, game
title - The name/title of the item
author - Optional, only used for books. If you specify an author you may, but are not required, to specify a title.
artist - Optional, only used for music. If you specify an artist you may, but are not required, to specify a title.

Returns:
{"search":[{"id":"122246","title":"Mad Max","platform":"NES","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"121582","title":"Max Payne 2: The Fall of Max Payne","platform":"PC","reviews":"1","alt":"false","reviewed":"false","listed":"false"},{"id":"127819","title":"Max Payne 2: The Fall of Max Payne","platform":"PS2","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"130438","title":"Max Payne 2: The Fall of Max Payne","platform":"Xbox","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"121258","title":"Blue Max","platform":"PC","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"121581","title":"Max Payne","platform":"PC","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"127818","title":"Max Payne","platform":"PS2","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"130437","title":"Max Payne","platform":"Xbox","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"122609","title":"The Adventures of Mighty Max","platform":"Genesis","reviews":"0","alt":"false","reviewed":"false","listed":"false"},{"id":"124362","title":"The Adventures of Mighty Max","platform":"SNES","reviews":"0","alt":"false","reviewed":"false","listed":"false"}]}




GET /1/list.format

Description: Retrieves all items on the specified list
Parameters:
id - the ID of the list

Returns:
{"listitem":[{"id":"73","type":"film","rating":"4.0","title":"Blood and Chocolate"},{"id":"61","type":"film","rating":"4.5","title":"Dangerous Beauty"},{"id":"8068","type":"film","rating":"4.5","title":"Notting Hill"},{"id":"113765","type":"film","rating":"4.5","title":"Ondine"},{"id":"8197","type":"film","rating":"3.0","title":"One Night with the King"},{"id":"10337","type":"film","rating":"4.0","title":"Sweet Home Alabama"},{"id":"11","type":"film","rating":"4.5","title":"The Time Traveler's Wife"},{"id":"93","type":"film","rating":"3.0","title":"Wild Child"}]}



POST /1/list.format

Description: Add item to a list
Parameters:
id - the ID of the list
item - the ID of the item to add


DELETE /1/list.format

Description: Remove an item from a list
Parameters:
id - the ID of the list
item - the ID of the item to remove




GET /1/lists.format

Description: Show the names and IDs of all your lists
Parameters:
id - optional, specify an ID if you only want the title of a single list

Returns:
{"list":[{"id":1,"title":"Wishlist"},{"id":2,"title":"Watched"},{"id":3,"title":"Blocked"},{"id":"86","title":"Favorite Feel-Good"},{"id":"78","title":"Favorite Comedy"},{"id":"79","title":"Favorite Action"},{"id":"80","title":"Favorite Classic"},{"id":"81","title":"Favorite Romance"},{"id":"87","title":"Favorite Quirky"},{"id":"105","title":"Childhood Cartoons"},{"id":"84","title":"Favorite Suspense"},{"id":"85","title":"Favorite Kids"},{"id":"88","title":"Favorite Drama"}]}



POST /1/lists.format

Description: Add a new list
Parameters:
name - the name of the list to add

Returns:
{"list":{"id":108}}



PUT /1/lists.format

Description: Rename a list
Parameters:
id - the ID of list to rename
name - the new name for the list

Returns:
{"list":{"id":108}}



DELETE /1/lists.format

Description: Delete a list
Parameters:
id - the ID of the list to delete




POST /1/item.format

Description: Add a new item. If you attempt to add an item that exists, the id for that item will be returned instead. Using this method as a search tool is a bad idea because existing data may vary slightly from what you are adding, resulting in duplicate titles

Note: This is subject to the same restrictions as normal additions on the site http://shortreviews.net/help/1-faq/#q-addtitle. A 400 error will be returned if you don't have permission

Parameters:
type - film, music, book, game
title - The name/title of the item
author - Required for books
artist - Required for music
year - Required for films
platform - Required for games. Values: pc, nes, genesis, gameboy, gamegear, snes, saturn, ps1, n64, dreamcast, ps2, gba, gc, xbox, ds, psp, xbox360, wii, ps3

Returns:
{"item":{"id":182062}}