doc/api.md

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