From 9c1ee29911e9196d8c78db2d38d9d497d3235e5b Mon Sep 17 00:00:00 2001 From: Tobias Diekershoff Date: Tue, 9 Sep 2014 08:41:58 +0200 Subject: [PATCH] current API documentation from the github wiki --- doc/api.md | 362 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 362 insertions(+) create mode 100644 doc/api.md diff --git a/doc/api.md b/doc/api.md new file mode 100644 index 0000000000..f36a79a5eb --- /dev/null +++ b/doc/api.md @@ -0,0 +1,362 @@ +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). + +Please refer to the linked documentation for further information. + +## Implemented API calls + +### General +#### Unsupported parameters +* cursor: Not implemented in StatusNet +* trim_user: Not implemented in StatusNet +* contributor_details: Not implemented in StatusNet +* place_id: Not implemented in StatusNet +* display_coordinates: Not implemented in StatusNet +* include_rts: To-Do +* include_my_retweet: Retweets in friendica are implemented in a different way + +#### Different behaviour +* 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. +* include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions. + +#### Return values +* cid: Contact id of the user (important for "contact_allow" and "contact_deny") +* network: network of the user + +### account/verify_credentials +#### Parameters +* skip_status: Don't show the "status" field. (Default: false) +* include_entities: "true" shows entities for pictures and links (Default: false) + +### statuses/update, statuses/update_with_media +#### Parameters +* title: Title of the status +* status: Status in text format +* htmlstatus: Status in HTML format +* in_reply_to_status_id +* lat: latitude +* long: longitude +* media: image data +* source: Application name +* group_allow +* contact_allow +* group_deny +* contact_deny +* network +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* trim_user +* place_id +* display_coordinates + +### users/search +#### Parameters +* q: name of the user + +#### Unsupported parameters +* page +* count +* include_entities + +### users/show +#### Parameters +* user_id: id of the user +* screen_name: screen name (for technical reasons, this value is not unique!) +* include_entities: "true" shows entities for pictures and links (Default: false) + +### statuses/home_timeline +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* exclude_replies: don't show replies (default: false) +* conversation_id: Shows all statuses of a given conversation. +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* include_rts +* trim_user +* contributor_details + +### statuses/friends_timeline +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* exclude_replies: don't show replies (default: false) +* conversation_id: Shows all statuses of a given conversation. +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* include_rts +* trim_user +* contributor_details + +### statuses/public_timeline +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* exclude_replies: don't show replies (default: false) +* conversation_id: Shows all statuses of a given conversation. +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* trim_user + +### statuses/show +#### Parameters +* id: message number +* conversation: if set to "1" show all messages of the conversation with the given id +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* include_my_retweet +* trim_user + +### statuses/retweet +#### Parameters +* id: message number +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* trim_user + +### statuses/destroy +#### Parameters +* id: message number +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* trim_user + +### statuses/mentions +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* include_rts +* trim_user +* contributor_details + +### statuses/replies +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* include_rts +* trim_user +* contributor_details + +### statuses/user_timeline +#### Parameters +* user_id: id of the user +* screen_name: screen name (for technical reasons, this value is not unique!) +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* exclude_replies: don't show replies (default: false) +* conversation_id: Shows all statuses of a given conversation. +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* include_rts +* trim_user +* contributor_details + +### conversation/show +Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id. + +#### Parameters +* id: id of the post +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* include_rts +* trim_user +* contributor_details + +### favorites +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* user_id +* screen_name + +Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array. + +### account/rate_limit_status + +### help/test + +### statuses/friends +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* user_id +* screen_name +* cursor + +Friendica doesn't allow showing friends of other users. + +### statuses/followers +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* user_id +* screen_name +* cursor + +Friendica doesn't allow showing followers of other users. + +### statusnet/config + +### statusnet/version + +### friends/ids +#### Parameters +* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) + +#### Unsupported parameters +* user_id +* screen_name +* cursor + +Friendica doesn't allow showing friends of other users. + +### followers/ids +#### Parameters +* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) + +#### Unsupported parameters +* user_id +* screen_name +* cursor + +Friendica doesn't allow showing followers of other users. + +### direct_messages/new +#### Parameters +* user_id: id of the user +* screen_name: screen name (for technical reasons, this value is not unique!) +* text: The message +* replyto: ID of the replied direct message +* title: Title of the direct message + +### direct_messages/conversation +Shows all direct messages of a conversation +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* getText: Defines the format of the status field. Can be "html" or "plain" +* uri: URI of the conversation + +### direct_messages/all +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* getText: Defines the format of the status field. Can be "html" or "plain" + +### direct_messages/sent +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* getText: Defines the format of the status field. Can be "html" or "plain" +* include_entities: "true" shows entities for pictures and links (Default: false) + +### direct_messages +#### Parameters +* count: Items per page (default: 20) +* page: page number +* since_id: minimal id +* max_id: maximum id +* getText: Defines the format of the status field. Can be "html" or "plain" +* include_entities: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters +* skip_status + +### oauth/request_token +#### Parameters +* oauth_callback + +#### Unsupported parameters +* x_auth_access_type + +### oauth/access_token +#### Parameters +* oauth_verifier + +#### Unsupported parameters +* x_auth_password +* x_auth_username +* x_auth_mode + +## Not Implemented API calls +The following list is extracted from the [API source file](https://github.com/friendica/friendica/blob/master/include/api.php) (at the very bottom): +* favorites/create +* favorites/destroy +* statuses/retweets_of_me +* friendships/create +* friendships/destroy +* friendships/exists +* friendships/show +* account/update_location +* account/update_profile_background_image +* account/update_profile_image +* blocks/create +* blocks/destroy + +The following are things from the Twitter API also not implemented in StatusNet: +* statuses/retweeted_to_me +* statuses/retweeted_by_me +* direct_messages/destroy +* account/end_session +* account/update_delivery_device +* notifications/follow +* notifications/leave +* blocks/exists +* blocks/blocking +* lists + +## Usage Examples +### BASH / cURL +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)). + + /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" + +### Python +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. + + def tweet(server, message, group_allow=None): + url = server + '/api/statuses/update' + urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True)) + +There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API. \ No newline at end of file -- 2.39.5