-Implemented API calls\r
-===\r
-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). \r
-\r
-Please refer to the linked documentation for further information.\r
-\r
-General\r
----\r
-\r
-### Unsupported parameters\r
-* cursor: Not implemented in StatusNet\r
-* trim_user: Not implemented in StatusNet\r
-* contributor_details: Not implemented in StatusNet\r
-* place_id: Not implemented in StatusNet\r
-* display_coordinates: Not implemented in StatusNet\r
-* include_rts: To-Do\r
-* include_my_retweet: Retweets in friendica are implemented in a different way\r
-\r
-### Different behaviour\r
-* 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.\r
-* include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.\r
-\r
-### Return values\r
-* cid: Contact id of the user (important for "contact_allow" and "contact_deny")\r
-* network: network of the user\r
-\r
-account/verify_credentials\r
----\r
-\r
-### Parameters\r
-* skip_status: Don't show the "status" field. (Default: false)\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-statuses/update, statuses/update_with_media\r
----\r
-\r
-### Parameters\r
-* title: Title of the status\r
-* status: Status in text format\r
-* htmlstatus: Status in HTML format\r
-* in_reply_to_status_id\r
-* lat: latitude\r
-* long: longitude\r
-* media: image data\r
-* source: Application name\r
-* group_allow\r
-* contact_allow\r
-* group_deny\r
-* contact_deny\r
-* network\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* trim_user\r
-* place_id\r
-* display_coordinates\r
-\r
-users/search\r
----\r
-\r
-### Parameters\r
-* q: name of the user \r
-\r
-### Unsupported parameters\r
-* page\r
-* count\r
-* include_entities\r
-\r
-users/show\r
----\r
-\r
-### Parameters\r
-* user_id: id of the user \r
-* screen_name: screen name (for technical reasons, this value is not unique!)\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-statuses/home_timeline\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* exclude_replies: don't show replies (default: false)\r
-* conversation_id: Shows all statuses of a given conversation.\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* include_rts \r
-* trim_user \r
-* contributor_details \r
-\r
-statuses/friends_timeline\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* exclude_replies: don't show replies (default: false)\r
-* conversation_id: Shows all statuses of a given conversation.\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* include_rts \r
-* trim_user \r
-* contributor_details \r
-\r
-statuses/public_timeline\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* exclude_replies: don't show replies (default: false)\r
-* conversation_id: Shows all statuses of a given conversation.\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* trim_user \r
-\r
-statuses/show\r
----\r
-\r
-### Parameters\r
-* id: message number\r
-* conversation: if set to "1" show all messages of the conversation with the given id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* include_my_retweet \r
-* trim_user \r
-\r
-statuses/retweet\r
----\r
-\r
-### Parameters\r
-* id: message number\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* trim_user \r
-\r
-statuses/destroy\r
----\r
-\r
-### Parameters\r
-* id: message number\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* trim_user \r
-\r
-statuses/mentions\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* include_rts \r
-* trim_user \r
-* contributor_details \r
-\r
-statuses/replies\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* include_rts \r
-* trim_user \r
-* contributor_details \r
-\r
-statuses/user_timeline\r
----\r
-\r
-### Parameters\r
-* user_id: id of the user \r
-* screen_name: screen name (for technical reasons, this value is not unique!)\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* exclude_replies: don't show replies (default: false)\r
-* conversation_id: Shows all statuses of a given conversation.\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* include_rts \r
-* trim_user \r
-* contributor_details \r
-\r
-conversation/show\r
----\r
-\r
-Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.\r
-\r
-### Parameters\r
-* id: id of the post\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* include_rts \r
-* trim_user \r
-* contributor_details \r
-\r
-favorites\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-\r
-Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array.\r
-\r
-account/rate_limit_status\r
----\r
-\r
-help/test\r
----\r
-\r
-statuses/friends\r
----\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-* cursor \r
-\r
-Friendica doesn't allow showing friends of other users.\r
-\r
-statuses/followers\r
----\r
-\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-* cursor \r
-\r
-Friendica doesn't allow showing followers of other users.\r
-\r
-statusnet/config\r
----\r
-\r
-statusnet/version\r
----\r
-\r
-friends/ids\r
----\r
-\r
-### Parameters\r
-* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
-\r
-### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-* cursor \r
-\r
-Friendica doesn't allow showing friends of other users.\r
-\r
-followers/ids\r
----\r
-\r
-Parameters\r
----\r
-\r
-* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
-\r
-### Unsupported parameters\r
-* user_id\r
-* screen_name\r
-* cursor \r
-\r
-Friendica doesn't allow showing followers of other users.\r
-\r
-direct_messages/new\r
----\r
-\r
-### Parameters\r
-* user_id: id of the user \r
-* screen_name: screen name (for technical reasons, this value is not unique!)\r
-* text: The message\r
-* replyto: ID of the replied direct message\r
-* title: Title of the direct message\r
-\r
-direct_messages/conversation\r
----\r
-\r
-Shows all direct messages of a conversation\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* getText: Defines the format of the status field. Can be "html" or "plain"\r
-* uri: URI of the conversation\r
-\r
-direct_messages/all\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* getText: Defines the format of the status field. Can be "html" or "plain"\r
-\r
-direct_messages/sent\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* getText: Defines the format of the status field. Can be "html" or "plain"\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-direct_messages\r
----\r
-\r
-### Parameters\r
-* count: Items per page (default: 20)\r
-* page: page number\r
-* since_id: minimal id\r
-* max_id: maximum id\r
-* getText: Defines the format of the status field. Can be "html" or "plain"\r
-* include_entities: "true" shows entities for pictures and links (Default: false)\r
-\r
-### Unsupported parameters\r
-* skip_status \r
-\r
-oauth/request_token\r
----\r
-\r
-### Parameters\r
-* oauth_callback \r
-\r
-### Unsupported parameters\r
-* x_auth_access_type \r
-\r
-oauth/access_token\r
----\r
-\r
-### Parameters\r
-* oauth_verifier \r
-\r
-### Unsupported parameters\r
-* x_auth_password \r
-* x_auth_username \r
-* x_auth_mode \r
-\r
-Not Implemented API calls\r
-===\r
-\r
-The following list is extracted from the [API source file](https://github.com/friendica/friendica/blob/master/include/api.php) (at the very bottom):\r
-* favorites/create\r
-* favorites/destroy\r
-* statuses/retweets_of_me\r
-* friendships/create\r
-* friendships/destroy\r
-* friendships/exists\r
-* friendships/show\r
-* account/update_location\r
-* account/update_profile_background_image\r
-* account/update_profile_image\r
-* blocks/create\r
-* blocks/destroy\r
-\r
-The following are things from the Twitter API also not implemented in StatusNet:\r
-* statuses/retweeted_to_me\r
-* statuses/retweeted_by_me\r
-* direct_messages/destroy\r
-* account/end_session\r
-* account/update_delivery_device\r
-* notifications/follow\r
-* notifications/leave\r
-* blocks/exists\r
-* blocks/blocking\r
-* lists\r
-\r
-Usage Examples\r
-===\r
-\r
-BASH / cURL\r
----\r
-\r
-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)).\r
-\r
- /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"\r
-\r
-Python\r
----\r
-\r
-The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.\r
-The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.\r
-\r
- def tweet(server, message, group_allow=None):\r
- url = server + '/api/statuses/update'\r
- urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))\r
-\r
-There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.\r
+# Using the APIs
+
+<!-- markdownlint-disable MD010 MD013 MD024 -->
+
+* [Home](help)
+
+Friendica offers multiple API endpoints to interface with third-party applications:
+
+- [Twitter](help/API-Twitter)
+- [Mastodon](help/API-Mastodon)
+- [Friendica-specific](help/API-Friendica)
+- [GNU Social](help/API-GNU-Social)
+
+## Usage
+
+### HTTP Method
+
+API endpoints can restrict the HTTP method used to request them.
+Using an invalid method results in HTTP error 405 "Method Not Allowed".
+
+### Authentication
+
+Friendica supports basic HTTP Auth and OAuth 1 to authenticate the user to the APIs.
+
+OAuth settings can be added by the user in web UI under [/settings/oauth/](/settings/oauth/).
+
+### Errors
+
+When an error occurs in API call, an HTTP error code is returned, with an error message
+Usually:
+
+* 400 Bad Request: if parameters are missing or items can't be found
+* 403 Forbidden: if the authenticated user is missing
+* 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
+* 501 Not Implemented: if the requested API doesn't exist
+* 500 Internal Server Error: on other error conditions
+
+Error body is
+
+json:
+
+```json
+{
+ "error": "Specific error message",
+ "request": "API path requested",
+ "code": "HTTP error code"
+}
+```
+
+xml:
+
+```xml
+<status>
+ <error>Specific error message</error>
+ <request>API path requested</request>
+ <code>HTTP error code</code>
+</status>
+```
+
+## Usage Examples
+
+### BASH / cURL
+
+```bash
+/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 [RSStoFriendika](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.
projects / friendica.git / blobdiff