doc-src/twitterapi

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