doc/api.md

   1 Implemented API calls\r
   2 ===\r
   3 The friendica API aims to be compatible to the [StatusNet API](http://status.net/wiki/Twitter-compatible_API) which aims to be compatible to the [Twitter API 1.0](https://dev.twitter.com/docs/api/1). \r
   4 \r
   5 Please refer to the linked documentation for further information.\r
   6 \r
   7 General\r
   8 ---\r
   9 \r
  10 ### Unsupported parameters\r
  11 * cursor: Not implemented in StatusNet\r
  12 * trim_user: Not implemented in StatusNet\r
  13 * contributor_details: Not implemented in StatusNet\r
  14 * place_id: Not implemented in StatusNet\r
  15 * display_coordinates: Not implemented in StatusNet\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/verify_credentials\r
  28 ---\r
  29 \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 statuses/update, statuses/update_with_media\r
  35 ---\r
  36 \r
  37 ### Parameters\r
  38 * title: Title of the status\r
  39 * status: Status in text format\r
  40 * htmlstatus: Status in HTML format\r
  41 * in_reply_to_status_id\r
  42 * lat: latitude\r
  43 * long: longitude\r
  44 * media: image data\r
  45 * source: Application name\r
  46 * group_allow\r
  47 * contact_allow\r
  48 * group_deny\r
  49 * contact_deny\r
  50 * network\r
  51 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  52 \r
  53 ### Unsupported parameters\r
  54 * trim_user\r
  55 * place_id\r
  56 * display_coordinates\r
  57 \r
  58 users/search\r
  59 ---\r
  60 \r
  61 ### Parameters\r
  62 * q: name of the user \r
  63 \r
  64 ### Unsupported parameters\r
  65 * page\r
  66 * count\r
  67 * include_entities\r
  68 \r
  69 users/show\r
  70 ---\r
  71 \r
  72 ### Parameters\r
  73 * user_id: id of the user \r
  74 * screen_name: screen name (for technical reasons, this value is not unique!)\r
  75 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  76 \r
  77 statuses/home_timeline\r
  78 ---\r
  79 \r
  80 ### Parameters\r
  81 * count: Items per page (default: 20)\r
  82 * page: page number\r
  83 * since_id: minimal id\r
  84 * max_id: maximum id\r
  85 * exclude_replies: don't show replies (default: false)\r
  86 * conversation_id: Shows all statuses of a given conversation.\r
  87 * include_entities: "true" shows entities for pictures and links (Default: false)\r
  88 \r
  89 ### Unsupported parameters\r
  90 * include_rts \r
  91 * trim_user \r
  92 * contributor_details \r
  93 \r
  94 statuses/friends_timeline\r
  95 ---\r
  96 \r
  97 ### Parameters\r
  98 * count: Items per page (default: 20)\r
  99 * page: page number\r
 100 * since_id: minimal id\r
 101 * max_id: maximum id\r
 102 * exclude_replies: don't show replies (default: false)\r
 103 * conversation_id: Shows all statuses of a given conversation.\r
 104 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 105 \r
 106 ### Unsupported parameters\r
 107 * include_rts \r
 108 * trim_user \r
 109 * contributor_details \r
 110 \r
 111 statuses/public_timeline\r
 112 ---\r
 113 \r
 114 ### Parameters\r
 115 * count: Items per page (default: 20)\r
 116 * page: page number\r
 117 * since_id: minimal id\r
 118 * max_id: maximum id\r
 119 * exclude_replies: don't show replies (default: false)\r
 120 * conversation_id: Shows all statuses of a given conversation.\r
 121 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 122 \r
 123 ### Unsupported parameters\r
 124 * trim_user \r
 125 \r
 126 statuses/show\r
 127 ---\r
 128 \r
 129 ### Parameters\r
 130 * id: message number\r
 131 * conversation: if set to "1" show all messages of the conversation with the given id\r
 132 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 133 \r
 134 ### Unsupported parameters\r
 135 * include_my_retweet \r
 136 * trim_user \r
 137 \r
 138 statuses/retweet\r
 139 ---\r
 140 \r
 141 ### Parameters\r
 142 * id: message number\r
 143 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 144 \r
 145 ### Unsupported parameters\r
 146 * trim_user \r
 147 \r
 148 statuses/destroy\r
 149 ---\r
 150 \r
 151 ### Parameters\r
 152 * id: message number\r
 153 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 154 \r
 155 ### Unsupported parameters\r
 156 * trim_user \r
 157 \r
 158 statuses/mentions\r
 159 ---\r
 160 \r
 161 ### Parameters\r
 162 * count: Items per page (default: 20)\r
 163 * page: page number\r
 164 * since_id: minimal id\r
 165 * max_id: maximum id\r
 166 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 167 \r
 168 ### Unsupported parameters\r
 169 * include_rts \r
 170 * trim_user \r
 171 * contributor_details \r
 172 \r
 173 statuses/replies\r
 174 ---\r
 175 \r
 176 ### Parameters\r
 177 * count: Items per page (default: 20)\r
 178 * page: page number\r
 179 * since_id: minimal id\r
 180 * max_id: maximum id\r
 181 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 182 \r
 183 ### Unsupported parameters\r
 184 * include_rts \r
 185 * trim_user \r
 186 * contributor_details \r
 187 \r
 188 statuses/user_timeline\r
 189 ---\r
 190 \r
 191 ### Parameters\r
 192 * user_id: id of the user \r
 193 * screen_name: screen name (for technical reasons, this value is not unique!)\r
 194 * count: Items per page (default: 20)\r
 195 * page: page number\r
 196 * since_id: minimal id\r
 197 * max_id: maximum id\r
 198 * exclude_replies: don't show replies (default: false)\r
 199 * conversation_id: Shows all statuses of a given conversation.\r
 200 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 201 \r
 202 ### Unsupported parameters\r
 203 * include_rts \r
 204 * trim_user \r
 205 * contributor_details \r
 206 \r
 207 conversation/show\r
 208 ---\r
 209 \r
 210 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.\r
 211 \r
 212 ### Parameters\r
 213 * id: id of the post\r
 214 * count: Items per page (default: 20)\r
 215 * page: page number\r
 216 * since_id: minimal id\r
 217 * max_id: maximum id\r
 218 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 219 \r
 220 ### Unsupported parameters\r
 221 * include_rts \r
 222 * trim_user \r
 223 * contributor_details \r
 224 \r
 225 favorites\r
 226 ---\r
 227 \r
 228 ### Parameters\r
 229 * count: Items per page (default: 20)\r
 230 * page: page number\r
 231 * since_id: minimal id\r
 232 * max_id: maximum id\r
 233 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 234 \r
 235 ### Unsupported parameters\r
 236 * user_id\r
 237 * screen_name\r
 238 \r
 239 Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array.\r
 240 \r
 241 account/rate_limit_status\r
 242 ---\r
 243 \r
 244 help/test\r
 245 ---\r
 246 \r
 247 statuses/friends\r
 248 ---\r
 249 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 250 \r
 251 ### Unsupported parameters\r
 252 * user_id\r
 253 * screen_name\r
 254 * cursor \r
 255 \r
 256 Friendica doesn't allow showing friends of other users.\r
 257 \r
 258 statuses/followers\r
 259 ---\r
 260 \r
 261 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 262 \r
 263 ### Unsupported parameters\r
 264 * user_id\r
 265 * screen_name\r
 266 * cursor \r
 267 \r
 268 Friendica doesn't allow showing followers of other users.\r
 269 \r
 270 statusnet/config\r
 271 ---\r
 272 \r
 273 statusnet/version\r
 274 ---\r
 275 \r
 276 friends/ids\r
 277 ---\r
 278 \r
 279 ### Parameters\r
 280 * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
 281 \r
 282 ### Unsupported parameters\r
 283 * user_id\r
 284 * screen_name\r
 285 * cursor \r
 286 \r
 287 Friendica doesn't allow showing friends of other users.\r
 288 \r
 289 followers/ids\r
 290 ---\r
 291 \r
 292 Parameters\r
 293 ---\r
 294 \r
 295 * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
 296 \r
 297 ### Unsupported parameters\r
 298 * user_id\r
 299 * screen_name\r
 300 * cursor \r
 301 \r
 302 Friendica doesn't allow showing followers of other users.\r
 303 \r
 304 direct_messages/new\r
 305 ---\r
 306 \r
 307 ### Parameters\r
 308 * user_id: id of the user \r
 309 * screen_name: screen name (for technical reasons, this value is not unique!)\r
 310 * text: The message\r
 311 * replyto: ID of the replied direct message\r
 312 * title: Title of the direct message\r
 313 \r
 314 direct_messages/conversation\r
 315 ---\r
 316 \r
 317 Shows all direct messages of a conversation\r
 318 ### Parameters\r
 319 * count: Items per page (default: 20)\r
 320 * page: page number\r
 321 * since_id: minimal id\r
 322 * max_id: maximum id\r
 323 * getText: Defines the format of the status field. Can be "html" or "plain"\r
 324 * uri: URI of the conversation\r
 325 \r
 326 direct_messages/all\r
 327 ---\r
 328 \r
 329 ### Parameters\r
 330 * count: Items per page (default: 20)\r
 331 * page: page number\r
 332 * since_id: minimal id\r
 333 * max_id: maximum id\r
 334 * getText: Defines the format of the status field. Can be "html" or "plain"\r
 335 \r
 336 direct_messages/sent\r
 337 ---\r
 338 \r
 339 ### Parameters\r
 340 * count: Items per page (default: 20)\r
 341 * page: page number\r
 342 * since_id: minimal id\r
 343 * max_id: maximum id\r
 344 * getText: Defines the format of the status field. Can be "html" or "plain"\r
 345 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 346 \r
 347 direct_messages\r
 348 ---\r
 349 \r
 350 ### Parameters\r
 351 * count: Items per page (default: 20)\r
 352 * page: page number\r
 353 * since_id: minimal id\r
 354 * max_id: maximum id\r
 355 * getText: Defines the format of the status field. Can be "html" or "plain"\r
 356 * include_entities: "true" shows entities for pictures and links (Default: false)\r
 357 \r
 358 ### Unsupported parameters\r
 359 * skip_status \r
 360 \r
 361 oauth/request_token\r
 362 ---\r
 363 \r
 364 ### Parameters\r
 365 * oauth_callback \r
 366 \r
 367 ### Unsupported parameters\r
 368 * x_auth_access_type \r
 369 \r
 370 oauth/access_token\r
 371 ---\r
 372 \r
 373 ### Parameters\r
 374 * oauth_verifier \r
 375 \r
 376 ### Unsupported parameters\r
 377 * x_auth_password \r
 378 * x_auth_username \r
 379 * x_auth_mode \r
 380 \r
 381 Not Implemented API calls\r
 382 ===\r
 383 \r
 384 The following list is extracted from the [API source file](https://github.com/friendica/friendica/blob/master/include/api.php) (at the very bottom):\r
 385 * favorites/create\r
 386 * favorites/destroy\r
 387 * statuses/retweets_of_me\r
 388 * friendships/create\r
 389 * friendships/destroy\r
 390 * friendships/exists\r
 391 * friendships/show\r
 392 * account/update_location\r
 393 * account/update_profile_background_image\r
 394 * account/update_profile_image\r
 395 * blocks/create\r
 396 * blocks/destroy\r
 397 \r
 398 The following are things from the Twitter API also not implemented in StatusNet:\r
 399 * statuses/retweeted_to_me\r
 400 * statuses/retweeted_by_me\r
 401 * direct_messages/destroy\r
 402 * account/end_session\r
 403 * account/update_delivery_device\r
 404 * notifications/follow\r
 405 * notifications/leave\r
 406 * blocks/exists\r
 407 * blocks/blocking\r
 408 * lists\r
 409 \r
 410 Usage Examples\r
 411 ===\r
 412 \r
 413 BASH / cURL\r
 414 ---\r
 415 \r
 416 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
 417 \r
 418     /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
 419 \r
 420 Python\r
 421 ---\r
 422 \r
 423 The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.\r
 424 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.\r
 425 \r
 426     def tweet(server, message, group_allow=None):\r
 427         url = server + '/api/statuses/update'\r
 428         urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))\r
 429 \r
 430 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.\r