Issue #565: First iteration of the Post API

* Documented the tu_posts table fields
* Created Post API documentation
Closes #565

docs/source/userguide/api/errors/apicalltypenotrecognised.rst

@@ -0,0 +1,16 @@
+APICallTpyeNotRecognisedException
+=================================
+This exception is thrown when you make an API call with a type that is not recognised.
+
+=======
+Example
+=======
+
+``api/v1/post.php?type=not_a_recognised_type&post_id=18152896965124096``::
+
+    {
+        "error":{
+            "type":"APICallTypeNotRecognised",
+            "message":"Your API call type not_a_recognised_type was not recognised."
+        }
+    }

docs/source/userguide/api/errors/index.rst

@@ -0,0 +1,11 @@
+API Errors
+==========
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   apicalltypenotrecognised
+   requiredargumentmissing
+   usernotfound

docs/source/userguide/api/errors/requiredargumentmissing.rst

@@ -0,0 +1,17 @@
+RequiredArgumentMissingException
+================================
+This exception is thrown when a required argument is missing from your API call. Required arguments are listed with
+each API type in the `ThinkUp Post API wiki <The ThinkUp Post API>`_.
+
+=======
+Example
+=======
+
+``api/v1/post.php?type=user_posts``::
+
+    {
+        "error":{
+            "type":"RequiredArgumentMissingException",
+            "message":"A request of type user_posts requires a user_id or username to be specified."
+        }
+    }

docs/source/userguide/api/errors/usernotfound.rst

@@ -0,0 +1,16 @@
+UserNotFoundException
+=====================
+This exception is thrown when you have queried for a user that does not exist in ThinkUp's database.
+
+=======
+Example
+=======
+
+``api/v1/post.php?type=user_posts&username=samwhat``::
+
+    {
+        "error":{
+            "type":"UserNotFoundException",
+            "message":"The user that you specified could not be found in our database."
+        }
+    }

docs/source/userguide/api/index.rst

@@ -0,0 +1,9 @@
+The ThinkUp API
+===============
+
+Contents:
+
+.. toctree::
+   :maxdepth: 3
+
+   posts/index

docs/source/userguide/api/posts/index.rst

@@ -0,0 +1,60 @@
+Post API
+========
+
+How does it work?
+-----------------
+
+The file to query for API results is located in <thinkup>/api/v1/post.php. There are a number of API call 
+"types" and these can be specified in the "type" GET variable. Different API call types have their own set of required 
+and optional parameters. Some of these are mapped to work in exactly the same way as the Twitter API but some are 
+ThinkUp-specific.
+
+The output from the API is going has been modelled to look as much like the
+`Twitter Mentions API  <http://dev.twitter.com/doc/get/statuses/mentions>`_ as possible. Any ThinkUp specific data can
+be found in a "thinkup" variable in each post and user when the output has been JSON decoded.
+
+**Important:** The ThinkUp API currently does not support any authentication methods. Because of this, you will not be
+able to retrieve protected posts with the API. The API will only return posts that are public on Twitter
+or published on a Facebook Page. (ThinkUp automatically marksl all Facebook user profile posts private.)
+
+How do I use it?
+----------------
+
+Using the API is quite simple. Let's say you wanted to make an API call of type "user_posts" for the user "samwhoo", your
+request would look like this:
+
+`http://example.com/your_thinkup_install/api/v1/post.php?type=user_posts&username=samwhoo`
+
+That call will output the latest 20 posts made by samwhoo (as the default number of posts to return is 20).
+
+Consistency
+-----------
+
+Unlike the Twitter API, the ThinkUp API tries its best to return to you the same format of data for every call to the
+API. The format that posts (tweets) are returned in remains consistent regardless of what API call you are making.
+
+This `Anatomy of a Tweet <http://www.scribd.com/doc/30146338/map-of-a-tweet>`_ PDF was one of our reference documents.
+It's a very good start for anyone wishing to learn the Twitter or ThinkUp API.
+
+Facebook Support
+----------------
+
+As of this moment, you **can** use the API to search for Facebook posts but it is untested and experimental. The aim of
+this first iteration of the API was to nail Twitter support. 
+
+Post API Call Reference
+-----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   post
+   post_replies
+   post_retweets
+   related_posts
+   user_mentions
+   user_posts
+   user_posts_in_range
+   user_questions
+   user_replies
+   ../errors/index

docs/source/userguide/api/posts/post.rst

@@ -0,0 +1,103 @@
+Post
+=====
+Gets a single post.
+
+**API type slug:** ``post``
+
+**Example usage:** ``api/v1/post.php?type=post&post_id=12345``
+
+==================
+Required arguments
+==================
+
+* **post_id**
+
+    The ID of the post to retrieve.
+
+==================
+Optional Arguments
+==================
+
+* **network**
+
+    The network to use in the call. Defaults to 'twitter'.
+
+* **include_entities**
+
+    Whether or not to include `Tweet Entities <http://dev.twitter.com/pages/tweet_entities>`_ in the output.
+    Defaults to false. This argument can be set to true by making it equal to either **1**, **t** or **true**.
+
+* **include_replies**
+
+    Whether or not to include replies to this post in the output. This argument is recursive and will retrieve replies
+    to replies also. Defaults to false. This argument can be set to true by making it equal to either **1**, **t** or
+    **true**.
+
+* **trim_user**
+
+    If set to true, this flag strips the user part of the output to just the user's ID and nothing else. Defaults to
+    false. This argument can be set to true by making it equal to either **1**, **t** or **true**.
+
+==============
+Example output
+==============
+
+``api/v1/post.php?post_id=18152896965124096`` (the API type defaults to ``post``)::
+
+    {
+        "id":18152896965124096,
+        "source":"web",
+        "location":"Wales, United Kingdom",
+        "place":null,
+        "geo":{
+            "coordinates":[
+                52.4699784,
+                -3.8303771
+            ]
+        },
+        "in_reply_to_user_id":20636385,
+        "is_reply_by_friend":false,
+        "in_reply_to_post_id":17764087211491328,
+        "in_rt_of_user_id":null,
+        "reply_retweet_distance":324,
+        "is_retweet_by_friend":false,
+        "favorited":false,
+        "all_retweets":0,
+        "text":"@Stellar190 Application in astronomy, you say? Do you have any examples? :) (I don't doubt it, I'm just curious)",
+        "created_at":"Fri Dec 24 03:56:02 +0000 2010",
+        "annotations":null,
+        "truncated":false,
+        "protected":false,
+        "coordinates":{
+            "coordinates":[
+                52.4699784,
+                -3.8303771
+            ]
+        },
+        "thinkup":{
+            "retweet_count_cache":0,
+            "reply_count_cache":2,
+            "old_retweet_count_cache":0,
+            "is_geo_encoded":1
+        },
+        "user":{
+            "id":69410725,
+            "location":"Wales, UK",
+            "description":"20 years old. Born and raised in Wales, UK. Programmer, British Mensa member, grapefruit, terrible at writing tag lines.",
+            "url":"http://lbak.co.uk",
+            "friend_count":225,
+            "followers_count":83,
+            "profile_image_url":"http://a1.twimg.com/profile_images/1140823002/28567_10150158194220371_544780370_11863380_6914499_n_normal.jpg",
+            "name":"Sam Rose",
+            "screen_name":"samwhoo",
+            "statuses_count":775,
+            "created_at":"Thu Aug 27 21:32:42 +0100 2009",
+            "favourites_count":36,
+            "utc_offset":3600,
+            "thinkup":{
+                "last_post":"0000-00-00 00:00:00",
+                "last_post_id":0,
+                "found_in":"Owner Status"
+            }
+        }
+    }