Friendica Communications Platform (please note that this is a clone of the repository at github, issues are handled there) https://friendi.ca
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

361 lines
11 KiB

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