doc/api.md

   1 Implemented API calls\r
   2 ===\r
   3 The Friendica API aims to be compatible to the [GNU Social API](http://skilledtests.com/wiki/Twitter-compatible_API) and the [Twitter API](https://dev.twitter.com/rest/public). \r
   4 \r
   5 Please refer to the linked documentation for further information.\r
   6 \r
   7 ## Implemented API calls\r
   8 \r
   9 ### General\r
  10 #### Unsupported parameters\r
  11 * cursor: Not implemented in GNU Social\r
  12 * trim_user: Not implemented in GNU Social\r
  13 * contributor_details: Not implemented in GNU Social\r
  14 * place_id: Not implemented in GNU Social\r
  15 * display_coordinates: Not implemented in GNU Social\r
  16 * include_rts: To-Do\r
  17 * include_my_retweet: Retweets in Friendica are implemented in a different way\r
  18 \r
  19 #### Different behaviour\r
  20 * screen_name: The nick name in friendica is only unique in each network but not for all networks. The users are searched in the following priority: Friendica, StatusNet/GNU Social, Diaspora, pump.io, Twitter. If no contact was found by this way, then the first contact is taken.\r
  21 * include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.\r
  22 \r
  23 #### Return values\r
  24 * cid: Contact id of the user (important for "contact_allow" and "contact_deny")\r
  25 * network: network of the user\r
  26 \r
  27 ### account/rate_limit_status\r
  28 \r
  29 ### account/verify_credentials\r
  30 #### Parameters\r
  31 * skip_status: Don't show the "status" field. (Default: false)\r
  32 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  33 \r
  34 ### conversation/show\r
  35 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.\r
  36 \r
  37 #### Parameters\r
  38 * id: id of the post\r
  39 * count: Items per page (default: 20)\r
  40 * page: page number\r
  41 * since_id: minimal id\r
  42 * max_id: maximum id\r
  43 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  44 \r
  45 #### Unsupported parameters\r
  46 * include_rts \r
  47 * trim_user \r
  48 * contributor_details \r
  49 \r
  50 ### direct_messages\r
  51 #### Parameters\r
  52 * count: Items per page (default: 20)\r
  53 * page: page number\r
  54 * since_id: minimal id\r
  55 * max_id: maximum id\r
  56 * getText: Defines the format of the status field. Can be "html" or "plain"\r
  57 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  58 \r
  59 #### Unsupported parameters\r
  60 * skip_status \r
  61 \r
  62 ### direct_messages/all\r
  63 #### Parameters\r
  64 * count: Items per page (default: 20)\r
  65 * page: page number\r
  66 * since_id: minimal id\r
  67 * max_id: maximum id\r
  68 * getText: Defines the format of the status field. Can be "html" or "plain"\r
  69 \r
  70 ### direct_messages/conversation\r
  71 Shows all direct messages of a conversation\r
  72 #### Parameters\r
  73 * count: Items per page (default: 20)\r
  74 * page: page number\r
  75 * since_id: minimal id\r
  76 * max_id: maximum id\r
  77 * getText: Defines the format of the status field. Can be "html" or "plain"\r
  78 * uri: URI of the conversation\r
  79 \r
  80 ### direct_messages/new\r
  81 #### Parameters\r
  82 * user_id: id of the user \r
  83 * screen_name: screen name (for technical reasons, this value is not unique!)\r
  84 * text: The message\r
  85 * replyto: ID of the replied direct message\r
  86 * title: Title of the direct message\r
  87 \r
  88 ### direct_messages/sent\r
  89 #### Parameters\r
  90 * count: Items per page (default: 20)\r
  91 * page: page number\r
  92 * since_id: minimal id\r
  93 * max_id: maximum id\r
  94 * getText: Defines the format of the status field. Can be "html" or "plain"\r
  95 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  96 \r
  97 ### favorites\r
  98 #### Parameters\r
  99 * count: Items per page (default: 20)\r
 100 * page: page number\r
 101 * since_id: minimal id\r
 102 * max_id: maximum id\r
 103 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 104 \r
 105 #### Unsupported parameters\r
 106 * user_id\r
 107 * screen_name\r
 108 \r
 109 Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array.\r
 110 \r
 111 ### favorites/create\r
 112 #### Parameters\r
 113 * id\r
 114 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 115 \r
 116 ### favorites/destroy\r
 117 #### Parameters\r
 118 * id\r
 119 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 120 \r
 121 ### followers/ids\r
 122 #### Parameters\r
 123 * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
 124 \r
 125 #### Unsupported parameters\r
 126 * user_id\r
 127 * screen_name\r
 128 * cursor \r
 129 \r
 130 Friendica doesn't allow showing followers of other users.\r
 131 \r
 132 ### friendica/photo\r
 133 #### Parameters\r
 134 * photo_id: Resource id of a photo.\r
 135 \r
 136 Returns data of a picture with the given resource.\r
 137 \r
 138 ### friendica/photos/list\r
 139 \r
 140 Returns a list of all photo resources of the logged in user.\r
 141 \r
 142 ### friends/ids\r
 143 #### Parameters\r
 144 * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
 145 \r
 146 #### Unsupported parameters\r
 147 * user_id\r
 148 * screen_name\r
 149 * cursor \r
 150 \r
 151 Friendica doesn't allow showing friends of other users.\r
 152 \r
 153 ### help/test\r
 154 \r
 155 ### media/upload\r
 156 #### Parameters\r
 157 * media: image data\r
 158 \r
 159 ### oauth/request_token\r
 160 #### Parameters\r
 161 * oauth_callback \r
 162 \r
 163 #### Unsupported parameters\r
 164 * x_auth_access_type \r
 165 \r
 166 ### oauth/access_token\r
 167 #### Parameters\r
 168 * oauth_verifier \r
 169 \r
 170 #### Unsupported parameters\r
 171 * x_auth_password \r
 172 * x_auth_username \r
 173 * x_auth_mode \r
 174 \r
 175 ### statuses/destroy\r
 176 #### Parameters\r
 177 * id: message number\r
 178 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 179 \r
 180 #### Unsupported parameters\r
 181 * trim_user \r
 182 \r
 183 ### statuses/followers\r
 184 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 185 \r
 186 ### statuses/friends\r
 187 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 188 \r
 189 ### statuses/friends_timeline\r
 190 #### Parameters\r
 191 * count: Items per page (default: 20)\r
 192 * page: page number\r
 193 * since_id: minimal id\r
 194 * max_id: maximum id\r
 195 * exclude_replies: don't show replies (default: false)\r
 196 * conversation_id: Shows all statuses of a given conversation.\r
 197 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 198 \r
 199 #### Unsupported parameters\r
 200 * include_rts \r
 201 * trim_user \r
 202 * contributor_details \r
 203 \r
 204 ### statuses/home_timeline\r
 205 #### Parameters\r
 206 * count: Items per page (default: 20)\r
 207 * page: page number\r
 208 * since_id: minimal id\r
 209 * max_id: maximum id\r
 210 * exclude_replies: don't show replies (default: false)\r
 211 * conversation_id: Shows all statuses of a given conversation.\r
 212 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 213 \r
 214 #### Unsupported parameters\r
 215 * include_rts \r
 216 * trim_user \r
 217 * contributor_details \r
 218 \r
 219 ### statuses/mentions\r
 220 #### Parameters\r
 221 * count: Items per page (default: 20)\r
 222 * page: page number\r
 223 * since_id: minimal id\r
 224 * max_id: maximum id\r
 225 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 226 \r
 227 #### Unsupported parameters\r
 228 * include_rts \r
 229 * trim_user \r
 230 * contributor_details \r
 231 \r
 232 ### statuses/public_timeline\r
 233 #### Parameters\r
 234 * count: Items per page (default: 20)\r
 235 * page: page number\r
 236 * since_id: minimal id\r
 237 * max_id: maximum id\r
 238 * exclude_replies: don't show replies (default: false)\r
 239 * conversation_id: Shows all statuses of a given conversation.\r
 240 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 241 \r
 242 #### Unsupported parameters\r
 243 * trim_user \r
 244 \r
 245 ### statuses/replies\r
 246 #### Parameters\r
 247 * count: Items per page (default: 20)\r
 248 * page: page number\r
 249 * since_id: minimal id\r
 250 * max_id: maximum id\r
 251 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 252 \r
 253 #### Unsupported parameters\r
 254 * include_rts \r
 255 * trim_user \r
 256 * contributor_details \r
 257 \r
 258 ### statuses/retweet\r
 259 #### Parameters\r
 260 * id: message number\r
 261 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 262 \r
 263 #### Unsupported parameters\r
 264 * trim_user \r
 265 \r
 266 ### statuses/show\r
 267 #### Parameters\r
 268 * id: message number\r
 269 * conversation: if set to "1" show all messages of the conversation with the given id\r
 270 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 271 \r
 272 #### Unsupported parameters\r
 273 * include_my_retweet \r
 274 * trim_user \r
 275 \r
 276 ### statuses/update, statuses/update_with_media\r
 277 #### Parameters\r
 278 * title: Title of the status\r
 279 * status: Status in text format\r
 280 * htmlstatus: Status in HTML format\r
 281 * in_reply_to_status_id\r
 282 * lat: latitude\r
 283 * long: longitude\r
 284 * media: image data\r
 285 * source: Application name\r
 286 * group_allow\r
 287 * contact_allow\r
 288 * group_deny\r
 289 * contact_deny\r
 290 * network\r
 291 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 292 * media_ids: (By now only a single value, no array) \r
 293 \r
 294 #### Unsupported parameters\r
 295 * trim_user\r
 296 * place_id\r
 297 * display_coordinates\r
 298 \r
 299 ### statuses/user_timeline\r
 300 #### Parameters\r
 301 * user_id: id of the user \r
 302 * screen_name: screen name (for technical reasons, this value is not unique!)\r
 303 * count: Items per page (default: 20)\r
 304 * page: page number\r
 305 * since_id: minimal id\r
 306 * max_id: maximum id\r
 307 * exclude_replies: don't show replies (default: false)\r
 308 * conversation_id: Shows all statuses of a given conversation.\r
 309 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 310 \r
 311 #### Unsupported parameters\r
 312 * include_rts \r
 313 * trim_user \r
 314 * contributor_details \r
 315 \r
 316 ### statusnet/config\r
 317 \r
 318 ### statusnet/version\r
 319 \r
 320 #### Unsupported parameters\r
 321 * user_id\r
 322 * screen_name\r
 323 * cursor \r
 324 \r
 325 Friendica doesn't allow showing followers of other users.\r
 326 \r
 327 ### users/search\r
 328 #### Parameters\r
 329 * q: name of the user \r
 330 \r
 331 #### Unsupported parameters\r
 332 * page\r
 333 * count\r
 334 * include_entities\r
 335 \r
 336 ### users/show\r
 337 #### Parameters\r
 338 * user_id: id of the user \r
 339 * screen_name: screen name (for technical reasons, this value is not unique!)\r
 340 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 341 \r
 342 #### Unsupported parameters\r
 343 * user_id\r
 344 * screen_name\r
 345 * cursor \r
 346 \r
 347 Friendica doesn't allow showing friends of other users.\r
 348 \r
 349 ## Not Implemented API calls\r
 350 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)\r
 351 \r
 352 * statuses/retweets_of_me\r
 353 * friendships/create\r
 354 * friendships/destroy\r
 355 * friendships/exists\r
 356 * friendships/show\r
 357 * account/update_profile_background_image\r
 358 * account/update_profile_image\r
 359 * blocks/create\r
 360 * blocks/destroy\r
 361 \r
 362 The following API calls from the Twitter API aren't implemented neither in Friendica nor in GNU Social:\r
 363 \r
 364 * statuses/mentions_timeline\r
 365 * statuses/retweets/:id\r
 366 * statuses/oembed\r
 367 * statuses/retweeters/ids\r
 368 * statuses/lookup\r
 369 * direct_messages/show\r
 370 * search/tweets\r
 371 * direct_messages/destroy\r
 372 * friendships/no_retweets/ids\r
 373 * friendships/incoming\r
 374 * friendships/outgoing\r
 375 * friendships/update\r
 376 * friends/list\r
 377 * friendships/lookup\r
 378 * account/settings\r
 379 * account/update_delivery_device\r
 380 * account/update_profile\r
 381 * account/update_profile_background_image\r
 382 * account/update_profile_image\r
 383 * blocks/list\r
 384 * blocks/ids\r
 385 * users/lookup\r
 386 * users/show\r
 387 * users/search\r
 388 * account/remove_profile_banner\r
 389 * account/update_profile_banner\r
 390 * users/profile_banner\r
 391 * mutes/users/create\r
 392 * mutes/users/destroy\r
 393 * mutes/users/ids\r
 394 * mutes/users/list\r
 395 * users/suggestions/:slug\r
 396 * users/suggestions\r
 397 * users/suggestions/:slug/members\r
 398 * favorites/list\r
 399 * lists/list\r
 400 * lists/statuses\r
 401 * lists/members/destroy\r
 402 * lists/memberships\r
 403 * lists/subscribers\r
 404 * lists/subscribers/create\r
 405 * lists/subscribers/show\r
 406 * lists/subscribers/destroy\r
 407 * lists/members/create_all\r
 408 * lists/members/show\r
 409 * lists/members\r
 410 * lists/members/create\r
 411 * lists/destroy\r
 412 * lists/update\r
 413 * lists/create\r
 414 * lists/show\r
 415 * lists/subscriptions\r
 416 * lists/members/destroy_all\r
 417 * lists/ownerships\r
 418 * saved_searches/list\r
 419 * saved_searches/show/:id\r
 420 * saved_searches/create\r
 421 * saved_searches/destroy/:id\r
 422 * geo/id/:place_id\r
 423 * geo/reverse_geocode\r
 424 * geo/search\r
 425 * geo/place\r
 426 * trends/place\r
 427 * trends/available\r
 428 * help/configuration\r
 429 * help/languages\r
 430 * help/privacy\r
 431 * help/tos\r
 432 * trends/closest\r
 433 * users/report_spam\r
 434 \r
 435 ## Usage Examples\r
 436 ### BASH / cURL\r
 437 Betamax has documentated some example API usage from a [bash script](https://en.wikipedia.org/wiki/Bash_(Unix_shell) employing [curl](https://en.wikipedia.org/wiki/CURL) (see [his posting](https://betamax65.de/display/betamax65/43539)).\r
 438 \r
 439     /usr/bin/curl -u USER:PASS https://YOUR.FRIENDICA.TLD/api/statuses/update.xml -d source="some source id" -d status="the status you want to post"\r
 440 \r
 441 ### Python\r
 442 The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python. The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.\r
 443 \r
 444     def tweet(server, message, group_allow=None):\r
 445         url = server + '/api/statuses/update'\r
 446         urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))\r
 447 \r
 448 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.\r