From f4eaf5842d0a7615c7b9cb81f354cf60f37f7300 Mon Sep 17 00:00:00 2001 From: Silke Meyer Date: Fri, 17 Apr 2015 18:17:44 +0200 Subject: [PATCH] sorted out the headings' md syntax --- doc/api.md | 238 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 153 insertions(+), 85 deletions(-) diff --git a/doc/api.md b/doc/api.md index f36a79a5e..fa9df1245 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1,11 +1,13 @@ +Implemented API calls +=== 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 +--- -### General -#### Unsupported parameters +### Unsupported parameters * cursor: Not implemented in StatusNet * trim_user: Not implemented in StatusNet * contributor_details: Not implemented in StatusNet @@ -14,21 +16,25 @@ Please refer to the linked documentation for further information. * include_rts: To-Do * include_my_retweet: Retweets in friendica are implemented in a different way -#### Different behaviour +### 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 +### Return values * cid: Contact id of the user (important for "contact_allow" and "contact_deny") * network: network of the user -### account/verify_credentials -#### Parameters +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 +statuses/update, statuses/update_with_media +--- + +### Parameters * title: Title of the status * status: Status in text format * htmlstatus: Status in HTML format @@ -44,28 +50,34 @@ Please refer to the linked documentation for further information. * network * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * trim_user * place_id * display_coordinates -### users/search -#### Parameters +users/search +--- + +### Parameters * q: name of the user -#### Unsupported parameters +### Unsupported parameters * page * count * include_entities -### users/show -#### Parameters +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 +statuses/home_timeline +--- + +### Parameters * count: Items per page (default: 20) * page: page number * since_id: minimal id @@ -74,13 +86,15 @@ Please refer to the linked documentation for further information. * conversation_id: Shows all statuses of a given conversation. * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * include_rts * trim_user * contributor_details -### statuses/friends_timeline -#### Parameters +statuses/friends_timeline +--- + +### Parameters * count: Items per page (default: 20) * page: page number * since_id: minimal id @@ -89,13 +103,15 @@ Please refer to the linked documentation for further information. * conversation_id: Shows all statuses of a given conversation. * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * include_rts * trim_user * contributor_details -### statuses/public_timeline -#### Parameters +statuses/public_timeline +--- + +### Parameters * count: Items per page (default: 20) * page: page number * since_id: minimal id @@ -104,63 +120,75 @@ Please refer to the linked documentation for further information. * conversation_id: Shows all statuses of a given conversation. * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * trim_user -### statuses/show -#### Parameters +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 +### Unsupported parameters * include_my_retweet * trim_user -### statuses/retweet -#### Parameters +statuses/retweet +--- + +### Parameters * id: message number * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * trim_user -### statuses/destroy -#### Parameters +statuses/destroy +--- + +### Parameters * id: message number * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * trim_user -### statuses/mentions -#### Parameters +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 +### Unsupported parameters * include_rts * trim_user * contributor_details -### statuses/replies -#### Parameters +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 +### Unsupported parameters * include_rts * trim_user * contributor_details -### statuses/user_timeline -#### Parameters +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) @@ -171,15 +199,17 @@ Please refer to the linked documentation for further information. * conversation_id: Shows all statuses of a given conversation. * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * include_rts * trim_user * contributor_details -### conversation/show +conversation/show +--- + Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id. -#### Parameters +### Parameters * id: id of the post * count: Items per page (default: 20) * page: page number @@ -187,86 +217,105 @@ Unofficial Twitter command. It shows all direct answers (excluding the original * max_id: maximum id * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * include_rts * trim_user * contributor_details -### favorites -#### Parameters +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 +### 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 +account/rate_limit_status +--- -### help/test +help/test +--- -### statuses/friends +statuses/friends +--- * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * user_id * screen_name * cursor Friendica doesn't allow showing friends of other users. -### statuses/followers +statuses/followers +--- + * include_entities: "true" shows entities for pictures and links (Default: false) -#### Unsupported parameters +### Unsupported parameters * user_id * screen_name * cursor Friendica doesn't allow showing followers of other users. -### statusnet/config +statusnet/config +--- -### statusnet/version +statusnet/version +--- -### friends/ids -#### Parameters +friends/ids +--- + +### Parameters * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) -#### Unsupported parameters +### Unsupported parameters * user_id * screen_name * cursor Friendica doesn't allow showing friends of other users. -### followers/ids -#### Parameters +followers/ids +--- + +Parameters +--- + * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) -#### Unsupported parameters +### Unsupported parameters * user_id * screen_name * cursor Friendica doesn't allow showing followers of other users. -### direct_messages/new -#### Parameters +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 +direct_messages/conversation +--- + Shows all direct messages of a conversation -#### Parameters +### Parameters * count: Items per page (default: 20) * page: page number * since_id: minimal id @@ -274,16 +323,20 @@ Shows all direct messages of a conversation * getText: Defines the format of the status field. Can be "html" or "plain" * uri: URI of the conversation -### direct_messages/all -#### Parameters +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 +direct_messages/sent +--- + +### Parameters * count: Items per page (default: 20) * page: page number * since_id: minimal id @@ -291,8 +344,10 @@ Shows all direct messages of a conversation * 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 +direct_messages +--- + +### Parameters * count: Items per page (default: 20) * page: page number * since_id: minimal id @@ -300,26 +355,32 @@ Shows all direct messages of a conversation * 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 +### Unsupported parameters * skip_status -### oauth/request_token -#### Parameters +oauth/request_token +--- + +### Parameters * oauth_callback -#### Unsupported parameters +### Unsupported parameters * x_auth_access_type -### oauth/access_token -#### Parameters +oauth/access_token +--- + +### Parameters * oauth_verifier -#### Unsupported parameters +### Unsupported parameters * x_auth_password * x_auth_username * x_auth_mode -## Not Implemented API calls +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 @@ -346,17 +407,24 @@ The following are things from the Twitter API also not implemented in StatusNet: * blocks/blocking * lists -## Usage Examples -### BASH / cURL +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. +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 +There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.