From 67bfb30f71f33c3e3fec53bf28d6c53d7920188f Mon Sep 17 00:00:00 2001 From: Tobias Diekershoff Date: Tue, 9 Sep 2014 08:41:35 +0200 Subject: [PATCH 1/5] copy of the Home.md so github has an index file to show --- doc/readme.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 doc/readme.md diff --git a/doc/readme.md b/doc/readme.md new file mode 100644 index 000000000..62bdd2001 --- /dev/null +++ b/doc/readme.md @@ -0,0 +1,47 @@ +Friendica Documentation and Resources +===================================== + +**Contents** + +* General functions - first steps + * [Account Basics](help/Account-Basics) + * [New User Quick Start](help/Quick-Start-guide) + * [Creating posts](help/Text_editor) + * [BBCode tag reference](help/BBCode) + * [Comment, sort and delete posts](help/Text_comment) + * [Profiles](help/Profiles) +* You and other user + * [Connectors](help/Connectors) + * [Making Friends](help/Making-Friends) + * [Groups and Privacy](help/Groups-and-Privacy) + * [Tags and Mentions](help/Tags-and-Mentions) + * [Community Forums](help/Forums) + * [Chats](help/Chats) +* Further information + * [Improve Performance](help/Improve-Performance) + * [Move Account](help/Move-Account) + * [Remove Account](help/Remove-Account) + * [Bugs and Issues](help/Bugs-and-Issues) + * [Frequently asked questions (FAQ)](help/FAQ) + +**Technical Documentation** + +* [Install](help/Install) +* [Settings](help/Settings) +* [Plugins](help/Plugins) +* [Installing Connectors (Facebook/Twitter/StatusNet)](help/Installing-Connectors) +* [Message Flow](help/Message-Flow) +* [Using SSL with Friendica](help/SSL) +* [Developers](help/Developers) +* [Twitter/StatusNet API Functions](help/api) + + +**External Resources** + +* [Main Website](http://friendica.com) +* [Mailing List Archive](http://librelist.com/browser/friendica/) + +**About** + +* [Site/Version Info](friendica) + From 9c1ee29911e9196d8c78db2d38d9d497d3235e5b Mon Sep 17 00:00:00 2001 From: Tobias Diekershoff Date: Tue, 9 Sep 2014 08:41:58 +0200 Subject: [PATCH 2/5] 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 000000000..f36a79a5e --- /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 From d2512f5aa5b14abbfba9b3eed6e79c842c49b4d6 Mon Sep 17 00:00:00 2001 From: Tobias Diekershoff Date: Sat, 13 Sep 2014 08:10:03 +0200 Subject: [PATCH 3/5] add API docs to home.md --- doc/Home.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Home.md b/doc/Home.md index 86a4eb647..62bdd2001 100644 --- a/doc/Home.md +++ b/doc/Home.md @@ -33,6 +33,7 @@ Friendica Documentation and Resources * [Message Flow](help/Message-Flow) * [Using SSL with Friendica](help/SSL) * [Developers](help/Developers) +* [Twitter/StatusNet API Functions](help/api) **External Resources** From de103ff27365a0f8a77a5b667f4cf0c079c33ff3 Mon Sep 17 00:00:00 2001 From: Tobias Diekershoff Date: Sun, 14 Sep 2014 09:06:47 +0200 Subject: [PATCH 4/5] added list of clients to the FAQ --- doc/FAQ.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/doc/FAQ.md b/doc/FAQ.md index c3c3e8bc2..f1a184388 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -12,6 +12,7 @@ User * **[What happens when an account is removed? Is it truly deleted?](help/FAQ#removed)** * **[Can I subscribe to a hashtag?](help/FAQ#hashtag)** * **[How to create a RSS feed of the stream?](help/FAQ#rss)** +* **[Are there any clients for friendica I can use](help/FAQ#clients)** * **[Where I can find help?](help/FAQ#help)** Admins @@ -130,6 +131,27 @@ RSS feed of the conversations at your site https://helpers.pyxis.uberspace.de/dfrn_poll/helpers/converse + + +**Are there any clients for friendica I can use** + +Friendica is using a [Twitter/StatusNet compatible API](help/api), which means you can use any Twitter/StatusNet/GNU Social client for your plattform as long as you can change the API path in its settings. Here is a list of known working clients + +* Android + * Friendica Client for Android + * AndStatus + * Twidere + * Mustard and Mustard-Mod +* Linux + * Hotot + * Choqok +* MacOS X + * Hotot +* Windows + * Hotot + +Depending on the features of the client you might encounter some glitches in usability, like being limited in the length of your postings to 140 characters and having no access to the [permission settings](help/Groups-and-Privacy). + **Where I can find help?** @@ -157,4 +179,4 @@ You can find the main respository [here](https://github.com/friendica/friendica) Addons are listed at [this page](https://github.com/friendica/friendica-addons). -If you are searching for new themes, you can find them at [Friendica-Themes.com](http://friendica-themes.com/) \ No newline at end of file +If you are searching for new themes, you can find them at [Friendica-Themes.com](http://friendica-themes.com/) From 94640d32fdc627b2403d72c5f5fac9522cedcd43 Mon Sep 17 00:00:00 2001 From: Tobias Diekershoff Date: Sun, 14 Sep 2014 09:17:21 +0200 Subject: [PATCH 5/5] missing ? --- doc/FAQ.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/FAQ.md b/doc/FAQ.md index f1a184388..59e5a7ade 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -12,7 +12,7 @@ User * **[What happens when an account is removed? Is it truly deleted?](help/FAQ#removed)** * **[Can I subscribe to a hashtag?](help/FAQ#hashtag)** * **[How to create a RSS feed of the stream?](help/FAQ#rss)** -* **[Are there any clients for friendica I can use](help/FAQ#clients)** +* **[Are there any clients for friendica I can use?](help/FAQ#clients)** * **[Where I can find help?](help/FAQ#help)** Admins @@ -133,7 +133,7 @@ RSS feed of the conversations at your site -**Are there any clients for friendica I can use** +**Are there any clients for friendica I can use?** Friendica is using a [Twitter/StatusNet compatible API](help/api), which means you can use any Twitter/StatusNet/GNU Social client for your plattform as long as you can change the API path in its settings. Here is a list of known working clients