Merge pull request #1144 from tobiasd/docs2014

documentation
This commit is contained in:
Tobias Diekershoff 2014-09-14 21:37:31 +02:00
commit c78c88c266
4 changed files with 433 additions and 1 deletions

View file

@ -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
<a name="clients"></a>
**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).
<a name="help"></a>
**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/)
If you are searching for new themes, you can find them at [Friendica-Themes.com](http://friendica-themes.com/)

View file

@ -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**

362
doc/api.md Normal file
View file

@ -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.

47
doc/readme.md Normal file
View file

@ -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)