<?xml-stylesheet href="/xsl/index.xsl" type="text/xsl"?>
<help>
<method>
Boktipset's API
</method>
<information>
Boktipset's API was created to make it easier for other web-pages and application to retrieve data from Boktipset.se. What it can and cannot be used for is stated in the EULA for Boktipsets API.
</information>
<security>
To make sure the information retrieved through the API is not missused a certain key ("accesskey") is issued for each application that allows it to be retrieved. If missused, the key can be revoked. 
For certain functions (like setting a grade) a special key for each user ("userkey") also is needed. The userkey can be obtained by using the authenticate method described below. In order to get personalized grades in return the userkey also has to be specified.
</security>
<calls>
<info>Calls to the API are made using either a html-request with parameters or sending an XML to the same URL. There are certain parameters that are used in all scripts:</info>
<parameter>
    <name>accesskey</name>
    <description>The accesskey for the application</description>
</parameter>
<parameter>
    <name>userkey</name>
    <description>The user key. Only needed in certain cases.</description>
</parameter>
<parameter>
    <name>format</name>
    <description>The format of the data to return. Valid values are xml and json. xml is the default return type.</description>
</parameter>
<parameter>
    <name>jsonwrapper</name>
    <description>When json is the return format, you can use this parameter to get the returned json wrapped in a function call. This is usefull to avoid cross site scripting.</description>
</parameter>
</calls>
<return>
The data can be returned formted either in xml or json. The data structures for the returned data is always the same for both formats. The data is always created in XML first, and then converted to JSON to make sure it conforms.
</return>
<help>
To get help for a certain call, call the script without parameters.
</help>
<functions>
<function>
    <name>Authenticate</name>
    <link>api/authenticate.cgi</link>
</function>
<function>
    <name>Information about a book</name>
    <link>book/book.cgi</link>
</function>
<function>
    <name>All comments for a book</name>
    <link>book/comments.cgi</link>
</function>
<function>
    <name>Show who is tracking a book</name>
    <link>book/tracking.cgi</link>
</function>
<function>
    <name>Search for books</name>
    <link>book/search.cgi</link>
</function>
<function>
    <name>Set a grade</name>
    <link>book/set_grade.cgi</link>
</function>
<function>
    <name>Post a comment</name>
    <link>book/submit_comment.cgi</link>
</function>
<function>
    <name>Events for a book</name>
    <link>book/events.cgi</link>
</function>
<function>
    <name>Information about a author</name>
    <link>author/author.cgi</link>
</function>
<function>
    <name>Information about a member</name>
    <link>member/profile.cgi</link>
</function>
<function>
    <name>A members shelf</name>
    <link>member/shelf.cgi</link>
</function>
<function>
    <name>Events for a member</name>
    <link>member/events.cgi</link>
</function>
<function>
    <name>All events for grouped events</name>
    <link>events/get_all_events.cgi</link>
</function>
<function>
    <name>Search for members</name>
    <link>member/search.cgi</link>
</function>
<function>
    <name>A list made by a member</name>
    <link>lists/memberlist.cgi</link>
</function>
<function>
    <name>A list based on statistics</name>
    <link>lists/statlist.cgi</link>
</function>
<function>
    <name>Create or edit lists</name>
    <link>lists/save_list.cgi</link>
</function>
<function>
    <name>Show a list of all genres available</name>
    <link>lists/genres.cgi</link>
</function>
<function>
    <name>Show a list of books for a genre</name>
    <link>lists/genre.cgi</link>
</function>
<function>
    <name>Add or remove from tracking lists</name>
    <link>lists/save_tracking.cgi</link>
</function>
<function>
    <name>Get information about a place</name>
    <link>places/place.cgi</link>
</function>
<function>
    <name>Get places for a book</name>
    <link>places/places_for_book.cgi</link>
</function>
<function>
    <name>Get places for a author</name>
    <link>places/places_for_author.cgi</link>
</function>
<function>
    <name>List check ins for a place, member, book, or author</name>
    <link>places/list_check_ins.cgi</link>
</function>
<function>
    <name>Get places for a bounding box</name>
    <link>places/places_for_coords.cgi</link>
</function>
<function>
    <name>Add a new place</name>
    <link>places/add_place.cgi</link>
</function>
<function>
    <name>Report an error on a place</name>
    <link>places/report_place.cgi</link>
</function>
<function>
    <name>Get blogposts</name>
    <link>blogapi/get_posts.cgi</link>
</function>
<function>
    <name>Get blogpost</name>
    <link>blogapi/get_post.cgi</link>
</function>
</functions>
<example>
 <requesturl><![CDATA[http://api.boktipset.se/index.cgi?accesskey=xxxxxxxxxxxxxxxxxxxx&userkey=yyyyyy&format=xml]]></requesturl>
 <request><![CDATA[<xml>
  <accesskey>xxxxxxxxxxxxxxxxxxxx</accesskey>
  <userkey>yyyyyy</userkey>
  <format>xml</format>
</xml>]]></request>
 <response><![CDATA[<xml>
.
.
.
</xml>]]></response>
</example>
</help>

