twitterapi 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431
  1. ## Authentication
  2. ### HTTP Basic authentication
  3. The API uses [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
  4. Note that this means that users with only an OpenID login cannot use the API; they have to add a
  5. password to their account using the control panel on the site.
  6. ### OAuth authentication
  7. OAuth 1.0a authentication for API resources is also supported. Generally, StatusNet's
  8. UI and API are similar to Twitter's for OAuth applications (if you're new to OAuth
  9. check out [Beginner’s Guide to OAuth](http://hueniverse.com/oauth/)).
  10. To use OAuth, you'll need to register your client application via the web interface
  11. and obtain a consumer key and secret. You can find the interface for application
  12. registration at [http://%%site.server%%/%%site.path%%settings/oauthapps](http://%%site.server%%/%%site.path%%settings/oauthapps).
  13. ## JSONP callbacks
  14. For API methods that return [JSON](https://en.wikipedia.org/wiki/JSON), an optional
  15. JSONP-style callback parameter is supported. If supplied, the response will be in
  16. JSONP format with a callback of the given name. To make it easier for clients to
  17. handle error conditions, HTTP error codes are suppressed, and the errors will be
  18. returned in the response body when using JSONP.
  19. ## Rate limiting
  20. There is currently no rate-limiting.
  21. ## Gotchas
  22. Some things to remember:
  23. * %%site.name%% supports the
  24. [OStatus federation protocol](https://en.wikipedia.org/wiki/OStatus) (as well as
  25. [OpenMicroBlogging](https://en.wikipedia.org/wiki/OpenMicroBlogging) for backwards
  26. compatibility), so many notices and friends' profiles may come from other servers.
  27. * User nicknames are unique, but they are not globally unique. Use the ID number
  28. instead.
  29. * Private streams are not implemented yet.
  30. * GNU social sites can be configured as private. In that case, all API methods
  31. require authentication, including the public timeline (see the 'config' method
  32. below).
  33. * If "Fancy URLs" are not enabled, urls from above need to include "index.php" at
  34. the root. ( e.g. http://example.org/statusnet/api becomes http://www.example.org/statusnet/index.php/api )
  35. * The `since_id` parameter does not work as documented by Twitter. Twitter says of
  36. `since_id`: "There are limits to the number of Tweets which can be accessed
  37. through the API. If the limit of Tweets has occured since the `since_id`, the
  38. `since_id` will be forced to the oldest ID available." However, GNU social will
  39. return the newest notices (or the newest back from max_id, if present)! Also, a
  40. `since_id` <= 0 will be ignored.
  41. ## Timeline resources
  42. ### statuses/public_timeline
  43. Returns the 20 most recent notices, including repeats if they exist, from
  44. non-protected users.
  45. ### statuses/home_timeline
  46. Returns the 20 most recent notices, including repeats if they exist, posted by the
  47. authenticating user and the users they follow. This is the same timeline seen by a
  48. user when they login to their instance. This method is identical to
  49. statuses/friends_timeline, except that this method always includes repeats.
  50. ### statuses/friends_timeline
  51. Alias of statuses/home_timeline
  52. ### statuses/friends_timeline/:username
  53. Alias of statuses/home_timeline for the specified username
  54. ### statuses/mentions
  55. Returns the 20 most recent mentions (notices containing @username) for the
  56. authenticating user.
  57. This method will not include repeats in the XML and JSON responses unless the
  58. include_rts parameter is set. The RSS and Atom responses will always include repeats
  59. as notices prefixed with RT.
  60. ### statuses/replies
  61. Alias of statuses/mentions
  62. ### statuses/replies/:username
  63. Alias of statuses/mentions for the specified username
  64. ### statuses/user_timeline
  65. Returns the 20 most recent notices posted by the authenticating user. It is also
  66. possible to request another user's timeline by using the screen\_name or user_id
  67. parameter. The other users timeline will only be visible if they are not protected,
  68. or if the authenticating user's follow request was accepted by the protected user.
  69. This method will not include repeats in the XML and JSON responses unless the
  70. include_rts parameter is set. The RSS and Atom responses will always include
  71. repeats as notices prefixed with RT, regardless of provided parameters.
  72. ### statuses/retweeted\_to_me
  73. Not implemented.
  74. ### statuses/retweeted\_by_me
  75. Not implemented.
  76. ### statuses/retweets\_of_me
  77. Not implemented.
  78. ## Status resources
  79. ### statuses/show/:id
  80. Returns a single notice, specified by the id parameter. The notice's author will be
  81. returned inline.
  82. ### statuses/update
  83. Post a new notice as the authenticating user.
  84. Additional 'media' parameter allows binary multimedia uploads (images, etc.). Format
  85. post data as multipart/form-data when using the 'media' parameter.
  86. ### statuses/destroy/:id
  87. Destroys the notice specified by the required ID parameter. The authenticating user
  88. must be the author of the specified notice. Returns the destroyed notice if successful.
  89. ### statuses/retweet/:id
  90. Repeats a notice. Returns the original notice with repeat details embedded.
  91. ## User resources
  92. ### statuses/friends
  93. Returns the user's subscriptions (friends) as an array of profiles.
  94. ### statuses/followers
  95. Returns the user's subscribers (followers) as an array of profiles.
  96. ### users/show
  97. Returns extended information of a given user, specified by ID or screen name as per
  98. the required id parameter.
  99. ## Direct message resources
  100. ### direct_messages
  101. Returns the 20 most recent direct messages sent to the authenticating user. The XML
  102. and JSON versions include detailed information about the sender and recipient user.
  103. ### direct_messages/sent
  104. Returns the 20 most recent direct messages sent by the authenticating user. The XML
  105. and JSON versions include detailed information about the sender and recipient user.
  106. ### direct_messages/new
  107. Sends a new direct message to the specified user from the authenticating user.
  108. Requires both the user and text parameters and must be a POST. Returns the sent
  109. message in the requested format if successful.
  110. ### direct_messages/destroy
  111. Not implemented.
  112. ## Friendships resources
  113. ### friendships/create
  114. Allows the authenticating users to follow the user specified in the ID parameter.
  115. Returns the befriended user in the requested format when successful. Returns a
  116. string describing the failure condition when unsuccessful.
  117. If you are already friends with the user a HTTP 403 may be returned, though for
  118. performance reasons you may get a 200 OK message even if the friendship already
  119. exists.
  120. Note that users cannot subscribe to remote profiles using this API.
  121. ### friendships/destroy
  122. Allows the authenticating users to unfollow the user specified in the ID parameter.
  123. Returns the unfollowed user in the requested format when successful. Returns a
  124. string describing the failure condition when unsuccessful.
  125. Users can unsubscribe to a remote profile using this API, but it's preferred to use
  126. numeric IDs to nicknames.
  127. ### friendships/exists
  128. Test for the existence of friendship between two users. Will return true if user\_a
  129. follows user_b, otherwise will return false. Authentication is required if either
  130. user A or user B are protected. Additionally the authenticating user must be a
  131. follower of the protected user.
  132. ### friendships/show
  133. Returns detailed information about the relationship between two users.
  134. ## Friends and subscribers resources
  135. ### friends/ids
  136. Returns an array of numeric IDs for every user the specified user is subscribed to.
  137. This method is powerful when used in conjunction with users/lookup.
  138. ### followers/ids
  139. Returns an array of numeric IDs for every user subscsribed to the specified user.
  140. This method is powerful when used in conjunction with users/lookup.
  141. ## Account resources
  142. ### account/verify_credentials
  143. Returns an HTTP 200 OK response code and a representation of the requesting user if
  144. authentication was successful; returns a 401 status code and an error message if
  145. not. Use this method to test if supplied user credentials are valid.
  146. ### account/end_session
  147. Not implemented.
  148. ### account/update\_delivery_device
  149. Not implemented.
  150. ### account/rate\_limit_status
  151. Returns the remaining number of API requests available to the requesting user before
  152. the API limit is reached.
  153. We have no rate limit, so this always returns 150 hits left.
  154. ### account/update\_profile\_background_image
  155. Updates the authenticating user's profile background image. This method can also be
  156. used to enable or disable the profile background image.
  157. ### account/update\_profile_image
  158. Updates the authenticating user's profile image. Note that this method expects raw
  159. multipart data, not a URL to an image.
  160. ## Favorite resources
  161. ### favorites
  162. Returns the 20 most recent favorite statuses for the authenticating or specified
  163. user in the requested format.
  164. ### favorites/create/:id
  165. Favorites the status specified in the ID parameter as the authenticating user.
  166. Returns the favorite status when successful.
  167. ### favorites/destroy/:id
  168. Un-favorites the status specified in the ID parameter as the authenticating user.
  169. Returns the un-favorited status in the requested format when successful.
  170. ## Notification resources
  171. ### notifications/follow
  172. Not implemented.
  173. ### notifications/leave
  174. Not implemented.
  175. ## Block resources
  176. ### blocks/create
  177. Blocks the specified user from following the authenticating user. In addition the
  178. blocked user will not show in the authenticating users mentions or timeline (unless
  179. retweeted by another user). If a follow or friend relationship exists it is
  180. destroyed.
  181. ### blocks/destroy
  182. Un-blocks the user specified in the ID parameter for the authenticating user.
  183. Returns the un-blocked user in the requested format when successful. If
  184. relationships existed before the block was instated, they will not be restored.
  185. ### blocks/exists
  186. Not implemented.
  187. ### blocks/blocking
  188. Not implemented.
  189. ## Help resources
  190. ### help/test
  191. Returns the string "ok" in the requested format with a 200 OK HTTP status code. This
  192. method is great for sending a HEAD request to determine our servers current time.
  193. ## OAuth resources
  194. It is strongly recommended you use HTTPS for all OAuth authorization steps.
  195. ### oauth/request_token
  196. Allows a Consumer application to obtain an OAuth Request Token to request user
  197. authorization. This method fulfills Section 6.1 of the OAuth 1.0 authentication
  198. flow. It is strongly recommended you use HTTPS for all OAuth authorization steps.
  199. ### oauth/authorize
  200. Allows a Consumer application to use an OAuth Request Token to request user
  201. authorization. This method fulfills Section 6.2 of the OAuth 1.0 authentication
  202. flow. Desktop applications must use this method (and cannot use GET oauth/authenticate).
  203. ### oauth/access_token
  204. Allows a Consumer application to exchange the OAuth Request Token for an OAuth
  205. Access Token. This method fulfills Section 6.3 of the OAuth 1.0 authentication flow.
  206. The OAuth access token may also be used for xAuth operations.
  207. ## Search
  208. The search method supports the following optional URL parameters:
  209. * **callback**: if supplied when using the JSON format, the response will use the
  210. JSONP format with a callback of the given name.
  211. * **rpp**: the number of notices to return per page, up to a max of 100.
  212. * **page**: the page number (starting at 1) to return.
  213. * **since_id:**: returns notices with ids greater than the given id.
  214. Note:
  215. * The search does not support operators, such as "from:", "to:" and booleans.
  216. * Notice content is HTML-encoded.
  217. ### search
  218. Returns relevant notices that match a specified query.
  219. ### Atom
  220. To request search results in Atom, append your URL-encoded query as a parameter to
  221. the search method and specify the Atom format:
  222. `%%site.server%%/%%site.path%%api/search.atom?q=<query>`
  223. ### JSON
  224. To request search results in JSON, append your URL-encoded query as a parameter to
  225. the search method and specify the JSON format:
  226. `%%site.server%%/%%site.path%%api/search.json?q=<query>`
  227. ## Additional resources
  228. These are extensions to the Twitter API that expose additional functionality.
  229. ### Group resources
  230. #### statusnet/groups/timeline
  231. Shows a group's timeline. Similar to other timeline resources.
  232. #### statusnet/groups/show
  233. Show a groups profile.
  234. #### statusnet/groups/create
  235. Create a new group.
  236. #### statusnet/groups/join
  237. Join a group.
  238. #### statusnet/groups/leave
  239. Leave a group.
  240. #### statusnet/groups/list
  241. Show the groups a given user is a member of.
  242. #### statusnet/groups/list_all
  243. List all local groups.
  244. #### statusnet/groups/membership
  245. List the members of a given group.
  246. #### statusnet/groups/is_member
  247. Determine whether a given user is a member of a given group.
  248. ### Tag resources
  249. #### statusnet/tags/timeline
  250. Shows a tag's timeline. Similar to other timeline resources.
  251. ### Media resources
  252. #### statusnet/media/upload
  253. Endpoint for uploading an image. Returns a URL that can be used in a status update.
  254. Format post data as multipart/form-data.
  255. ### Configuration
  256. #### statusnet/config
  257. Show an instance's configuration information.
  258. Of special note is the `<private>` element (config/site/private), which indicates
  259. whether a site is private. When a site is configured as private every other API
  260. method requires authentication, including the public timeline (`/api/statuses/public_timeline.format`).