Updated Friendica API (markdown)

annando 2014-09-06 22:40:01 -07:00
parent 753938173a
commit 44bbc4370a

@ -1,353 +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). 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 ## 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
* place_id: Not implemented in StatusNet * place_id: Not implemented in StatusNet
* display_coordinates: Not implemented in StatusNet * display_coordinates: Not implemented in StatusNet
* 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
* in_reply_to_status_id * in_reply_to_status_id
* lat: latitude * lat: latitude
* long: longitude * long: longitude
* media: image data * media: image data
* source: Application name * source: Application name
* group_allow * group_allow
* contact_allow * contact_allow
* group_deny * group_deny
* contact_deny * contact_deny
* 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/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 ### users/show
#### Parameters #### Parameters
* count: Items per page (default: 20) * q: name of the user
* page: page number
* since_id: minimal id #### Unsupported parameters
* max_id: maximum id * page
* exclude_replies: don't show replies (default: false) * count
* conversation_id: Shows all statuses of a given conversation. * include_entities
* include_entities: "true" shows entities for pictures and links (Default: false)
### statuses/home_timeline
#### Unsupported parameters #### Parameters
* include_rts * count: Items per page (default: 20)
* trim_user * page: page number
* contributor_details * since_id: minimal id
* max_id: maximum id
### statuses/friends_timeline * exclude_replies: don't show replies (default: false)
#### Parameters * conversation_id: Shows all statuses of a given conversation.
* count: Items per page (default: 20) * include_entities: "true" shows entities for pictures and links (Default: false)
* page: page number
* since_id: minimal id #### Unsupported parameters
* max_id: maximum id * include_rts
* exclude_replies: don't show replies (default: false) * trim_user
* conversation_id: Shows all statuses of a given conversation. * contributor_details
* include_entities: "true" shows entities for pictures and links (Default: false)
### statuses/friends_timeline
#### Unsupported parameters #### Parameters
* include_rts * count: Items per page (default: 20)
* trim_user * page: page number
* contributor_details * since_id: minimal id
* max_id: maximum id
### statuses/public_timeline * exclude_replies: don't show replies (default: false)
#### Parameters * conversation_id: Shows all statuses of a given conversation.
* count: Items per page (default: 20) * include_entities: "true" shows entities for pictures and links (Default: false)
* page: page number
* since_id: minimal id #### Unsupported parameters
* max_id: maximum id * include_rts
* exclude_replies: don't show replies (default: false) * trim_user
* conversation_id: Shows all statuses of a given conversation. * contributor_details
* include_entities: "true" shows entities for pictures and links (Default: false)
### statuses/public_timeline
#### Unsupported parameters #### Parameters
* trim_user * count: Items per page (default: 20)
* page: page number
### statuses/show * since_id: minimal id
#### Parameters * max_id: maximum id
* id: message number * exclude_replies: don't show replies (default: false)
* conversation: if set to "1" show all messages of the conversation with the given id * 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_my_retweet * trim_user
* trim_user
### statuses/show
### statuses/retweet #### Parameters
#### Parameters * id: message number
* 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) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters #### Unsupported parameters
* trim_user * include_my_retweet
* trim_user
### statuses/destroy
#### Parameters ### statuses/retweet
* id: message number #### Parameters
* include_entities: "true" shows entities for pictures and links (Default: false) * id: message number
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters
* trim_user #### Unsupported parameters
* trim_user
### statuses/mentions
#### Parameters ### statuses/destroy
* count: Items per page (default: 20) #### Parameters
* page: page number * id: message number
* since_id: minimal id * include_entities: "true" shows entities for pictures and links (Default: false)
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters
* trim_user
#### Unsupported parameters
* include_rts ### statuses/mentions
* trim_user #### Parameters
* contributor_details * count: Items per page (default: 20)
* page: page number
### statuses/replies * since_id: minimal id
#### Parameters * max_id: maximum id
* count: Items per page (default: 20) * include_entities: "true" shows entities for pictures and links (Default: false)
* page: page number
* since_id: minimal id #### Unsupported parameters
* max_id: maximum id * include_rts
* include_entities: "true" shows entities for pictures and links (Default: false) * trim_user
* contributor_details
#### Unsupported parameters
* include_rts ### statuses/replies
* trim_user #### Parameters
* contributor_details * count: Items per page (default: 20)
* page: page number
### statuses/user_timeline * since_id: minimal id
#### Parameters * max_id: maximum id
* user_id: id of the user * include_entities: "true" shows entities for pictures and links (Default: false)
* screen_name: screen name (for technical reasons, this value is not unique!)
* count: Items per page (default: 20) #### Unsupported parameters
* page: page number * include_rts
* since_id: minimal id * trim_user
* max_id: maximum id * contributor_details
* exclude_replies: don't show replies (default: false)
* conversation_id: Shows all statuses of a given conversation. ### statuses/user_timeline
* include_entities: "true" shows entities for pictures and links (Default: false) #### Parameters
* user_id: id of the user
#### Unsupported parameters * screen_name: screen name (for technical reasons, this value is not unique!)
* include_rts * count: Items per page (default: 20)
* trim_user * page: page number
* contributor_details * since_id: minimal id
* max_id: maximum id
### conversation/show * exclude_replies: don't show replies (default: false)
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id. * conversation_id: Shows all statuses of a given conversation.
* include_entities: "true" shows entities for pictures and links (Default: false)
#### Parameters
* id: id of the post #### Unsupported parameters
* count: Items per page (default: 20) * include_rts
* page: page number * trim_user
* since_id: minimal id * contributor_details
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false) ### conversation/show
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
#### Unsupported parameters
* include_rts #### Parameters
* trim_user * id: id of the post
* contributor_details * count: Items per page (default: 20)
* page: page number
### favorites * since_id: minimal id
#### Parameters * max_id: maximum id
* count: Items per page (default: 20) * include_entities: "true" shows entities for pictures and links (Default: false)
* page: page number
* since_id: minimal id #### Unsupported parameters
* max_id: maximum id * include_rts
* include_entities: "true" shows entities for pictures and links (Default: false) * trim_user
* contributor_details
#### Unsupported parameters
* user_id ### favorites
* screen_name #### Parameters
* count: Items per page (default: 20)
Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array. * page: page number
* since_id: minimal id
### account/rate_limit_status * max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false)
### help/test
#### Unsupported parameters
### statuses/friends * user_id
* include_entities: "true" shows entities for pictures and links (Default: false) * screen_name
#### Unsupported parameters Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array.
* user_id
* screen_name ### account/rate_limit_status
* cursor
### help/test
Friendica doesn't allow showing friends of other users.
### statuses/friends
### 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 friends of other users.
Friendica doesn't allow showing followers of other users.
### statuses/followers
### statusnet/config * include_entities: "true" shows entities for pictures and links (Default: false)
### statusnet/version #### Unsupported parameters
* user_id
### friends/ids * screen_name
#### Parameters * cursor
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
Friendica doesn't allow showing followers of other users.
#### Unsupported parameters
* user_id ### statusnet/config
* screen_name
* cursor ### statusnet/version
Friendica doesn't allow showing friends of other users. ### friends/ids
#### Parameters
### followers/ids * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
#### Parameters
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) #### Unsupported parameters
* user_id
#### Unsupported parameters * screen_name
* user_id * cursor
* screen_name
* cursor Friendica doesn't allow showing friends of other users.
Friendica doesn't allow showing followers of other users. ### followers/ids
#### Parameters
### direct_messages/new * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
#### Parameters
* user_id: id of the user #### Unsupported parameters
* screen_name: screen name (for technical reasons, this value is not unique!) * user_id
* text: The message * screen_name
* replyto: ID of the replied direct message * cursor
* title: Title of the direct message
Friendica doesn't allow showing followers of other users.
### direct_messages/conversation
Shows all direct messages of a conversation ### direct_messages/new
#### Parameters #### Parameters
* count: Items per page (default: 20) * user_id: id of the user
* page: page number * screen_name: screen name (for technical reasons, this value is not unique!)
* since_id: minimal id * text: The message
* max_id: maximum id * replyto: ID of the replied direct message
* getText: Defines the format of the status field. Can be "html" or "plain" * title: Title of the direct message
* uri: URI of the conversation
### direct_messages/conversation
### direct_messages/all 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
* 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"
* uri: URI of the conversation
### direct_messages/sent
#### Parameters ### direct_messages/all
* count: Items per page (default: 20) #### Parameters
* page: page number * count: Items per page (default: 20)
* since_id: minimal id * page: page number
* max_id: maximum id * since_id: minimal id
* getText: Defines the format of the status field. Can be "html" or "plain" * max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false) * getText: Defines the format of the status field. Can be "html" or "plain"
### direct_messages ### 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
* 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"
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters ### direct_messages
* skip_status #### Parameters
* count: Items per page (default: 20)
### oauth/request_token * page: page number
#### Parameters * since_id: minimal id
* oauth_callback * max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
#### Unsupported parameters * include_entities: "true" shows entities for pictures and links (Default: false)
* x_auth_access_type
#### Unsupported parameters
### oauth/access_token * skip_status
#### Parameters
* oauth_verifier ### oauth/request_token
#### Parameters
#### Unsupported parameters * oauth_callback
* x_auth_password
* x_auth_username #### Unsupported parameters
* x_auth_mode * x_auth_access_type
## Not Implemented API calls ### oauth/access_token
The following list is extracted from the [API source file](https://github.com/friendica/friendica/blob/master/include/api.php) (at the very bottom): #### Parameters
* favorites/create * oauth_verifier
* favorites/destroy
* statuses/retweets_of_me #### Unsupported parameters
* friendships/create * x_auth_password
* friendships/destroy * x_auth_username
* friendships/exists * x_auth_mode
* friendships/show
* account/update_location ## Not Implemented API calls
* account/update_profile_background_image The following list is extracted from the [API source file](https://github.com/friendica/friendica/blob/master/include/api.php) (at the very bottom):
* account/update_profile_image * favorites/create
* blocks/create * favorites/destroy
* blocks/destroy * statuses/retweets_of_me
* friendships/create
The following are things from the Twitter API also not implemented in StatusNet: * friendships/destroy
* statuses/retweeted_to_me * friendships/exists
* statuses/retweeted_by_me * friendships/show
* direct_messages/destroy * account/update_location
* account/end_session * account/update_profile_background_image
* account/update_delivery_device * account/update_profile_image
* notifications/follow * blocks/create
* notifications/leave * blocks/destroy
* blocks/exists
* blocks/blocking The following are things from the Twitter API also not implemented in StatusNet:
* lists * statuses/retweeted_to_me
* statuses/retweeted_by_me
## Usage Examples * direct_messages/destroy
### BASH / cURL * account/end_session
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)). * account/update_delivery_device
* notifications/follow
/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" * notifications/leave
* blocks/exists
### Python * blocks/blocking
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. * lists
def tweet(server, message, group_allow=None): ## Usage Examples
url = server + '/api/statuses/update' ### BASH / cURL
urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True)) 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. There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.