clones/friendica
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

sorted out the headings' md syntax

This commit is contained in:
Silke Meyer 2015-04-17 18:17:44 +02:00
parent 7faf4de3af
commit f4eaf5842d
1 changed files with 153 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

238
doc/api.md
View File

@ -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). 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. Please refer to the linked documentation for further information.
## Implemented API calls General
---
### General ### Unsupported parameters
#### Unsupported parameters
* cursor: Not implemented in StatusNet * cursor: Not implemented in StatusNet
* trim_user: Not implemented in StatusNet * trim_user: Not implemented in StatusNet
* contributor_details: 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_rts: To-Do
* include_my_retweet: Retweets in friendica are implemented in a different way * 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. * 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. * 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") * cid: Contact id of the user (important for "contact_allow" and "contact_deny")
* network: network of the user * network: network of the user
### account/verify_credentials account/verify_credentials
#### Parameters ---
### Parameters
* skip_status: Don't show the "status" field. (Default: false) * skip_status: Don't show the "status" field. (Default: false)
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
### statuses/update, statuses/update_with_media statuses/update, statuses/update_with_media
#### Parameters ---
### Parameters
* title: Title of the status * title: Title of the status
* status: Status in text format * status: Status in text format
* htmlstatus: Status in HTML format * htmlstatus: Status in HTML format
@ -44,28 +50,34 @@ Please refer to the linked documentation for further information.
* network * network
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* trim_user * trim_user
* place_id * place_id
* display_coordinates * display_coordinates
### users/search users/search
#### Parameters ---
### Parameters
* q: name of the user * q: name of the user
#### Unsupported parameters ### Unsupported parameters
* page * page
* count * count
* include_entities * include_entities
### users/show users/show
#### Parameters ---
### Parameters
* user_id: id of the user * user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!) * screen_name: screen name (for technical reasons, this value is not unique!)
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
### statuses/home_timeline statuses/home_timeline
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * 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. * conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* include_rts * include_rts
* trim_user * trim_user
* contributor_details * contributor_details
### statuses/friends_timeline statuses/friends_timeline
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * 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. * conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* include_rts * include_rts
* trim_user * trim_user
* contributor_details * contributor_details
### statuses/public_timeline statuses/public_timeline
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * 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. * conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* trim_user * trim_user
### statuses/show statuses/show
#### Parameters ---
### Parameters
* id: message number * id: message number
* conversation: if set to "1" show all messages of the conversation with the given id * 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) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* include_my_retweet * include_my_retweet
* trim_user * trim_user
### statuses/retweet statuses/retweet
#### Parameters ---
### Parameters
* id: message number * id: message number
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* trim_user * trim_user
### statuses/destroy statuses/destroy
#### Parameters ---
### Parameters
* id: message number * id: message number
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* trim_user * trim_user
### statuses/mentions statuses/mentions
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * since_id: minimal id
* max_id: maximum id * max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* include_rts * include_rts
* trim_user * trim_user
* contributor_details * contributor_details
### statuses/replies statuses/replies
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * since_id: minimal id
* max_id: maximum id * max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* include_rts * include_rts
* trim_user * trim_user
* contributor_details * contributor_details
### statuses/user_timeline statuses/user_timeline
#### Parameters ---
### Parameters
* user_id: id of the user * user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!) * screen_name: screen name (for technical reasons, this value is not unique!)
* count: Items per page (default: 20) * 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. * conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* include_rts * include_rts
* trim_user * trim_user
* contributor_details * contributor_details
### conversation/show conversation/show
---
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id. Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
#### Parameters ### Parameters
* id: id of the post * id: id of the post
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -187,86 +217,105 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
* max_id: maximum id * max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* include_rts * include_rts
* trim_user * trim_user
* contributor_details * contributor_details
### favorites favorites
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * since_id: minimal id
* max_id: maximum id * max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* user_id * user_id
* screen_name * 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. 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) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* user_id * user_id
* screen_name * screen_name
* cursor * cursor
Friendica doesn't allow showing friends of other users. Friendica doesn't allow showing friends of other users.
### statuses/followers statuses/followers
---
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* user_id * user_id
* screen_name * screen_name
* cursor * cursor
Friendica doesn't allow showing followers of other users. Friendica doesn't allow showing followers of other users.
### statusnet/config statusnet/config
---
### statusnet/version statusnet/version
---
### friends/ids friends/ids
#### Parameters ---
### Parameters
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
#### Unsupported parameters ### Unsupported parameters
* user_id * user_id
* screen_name * screen_name
* cursor * cursor
Friendica doesn't allow showing friends of other users. Friendica doesn't allow showing friends of other users.
### followers/ids followers/ids
#### Parameters ---
Parameters
---
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
#### Unsupported parameters ### Unsupported parameters
* user_id * user_id
* screen_name * screen_name
* cursor * cursor
Friendica doesn't allow showing followers of other users. Friendica doesn't allow showing followers of other users.
### direct_messages/new direct_messages/new
#### Parameters ---
### Parameters
* user_id: id of the user * user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!) * screen_name: screen name (for technical reasons, this value is not unique!)
* text: The message * text: The message
* replyto: ID of the replied direct message * replyto: ID of the replied direct message
* title: Title of the direct message * title: Title of the direct message
### direct_messages/conversation direct_messages/conversation
---
Shows all direct messages of a conversation Shows all direct messages of a conversation
#### Parameters ### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * 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" * getText: Defines the format of the status field. Can be "html" or "plain"
* uri: URI of the conversation * uri: URI of the conversation
### direct_messages/all direct_messages/all
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * since_id: minimal id
* max_id: maximum id * max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain" * getText: Defines the format of the status field. Can be "html" or "plain"
### direct_messages/sent direct_messages/sent
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * 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" * getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
### direct_messages direct_messages
#### Parameters ---
### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
* since_id: minimal id * 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" * getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### Unsupported parameters
* skip_status * skip_status
### oauth/request_token oauth/request_token
#### Parameters ---
### Parameters
* oauth_callback * oauth_callback
#### Unsupported parameters ### Unsupported parameters
* x_auth_access_type * x_auth_access_type
### oauth/access_token oauth/access_token
#### Parameters ---
### Parameters
* oauth_verifier * oauth_verifier
#### Unsupported parameters ### Unsupported parameters
* x_auth_password * x_auth_password
* x_auth_username * x_auth_username
* x_auth_mode * 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): 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/create
* favorites/destroy * favorites/destroy
@ -346,17 +407,24 @@ The following are things from the Twitter API also not implemented in StatusNet:
* blocks/blocking * blocks/blocking
* lists * lists
## Usage Examples Usage Examples
### BASH / cURL ===
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)). 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" /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 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. ---
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): def tweet(server, message, group_allow=None):
url = server + '/api/statuses/update' url = server + '/api/statuses/update'
urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True)) 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. There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.