sorted out the headings' md syntax
This commit is contained in:
Silke Meyer
parent
7faf4de3af
commit
f4eaf5842d
238
doc/api.md
238
doc/api.md
|
|
@ -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).
|
||||
|
||||
Please refer to the linked documentation for further information.
|
||||
|
||||
## Implemented API calls
|
||||
General
|
||||
---
|
||||
|
||||
### General
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* cursor: Not implemented in StatusNet
|
||||
* trim_user: 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_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.
|
||||
* 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")
|
||||
* network: network of the user
|
||||
|
||||
### account/verify_credentials
|
||||
#### Parameters
|
||||
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
|
||||
statuses/update, statuses/update_with_media
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* title: Title of the status
|
||||
* status: Status in text format
|
||||
* htmlstatus: Status in HTML format
|
||||
|
|
@ -44,28 +50,34 @@ Please refer to the linked documentation for further information.
|
|||
* network
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* trim_user
|
||||
* place_id
|
||||
* display_coordinates
|
||||
|
||||
### users/search
|
||||
#### Parameters
|
||||
users/search
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* q: name of the user
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* page
|
||||
* count
|
||||
* include_entities
|
||||
|
||||
### users/show
|
||||
#### Parameters
|
||||
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
|
||||
statuses/home_timeline
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* 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.
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
### statuses/friends_timeline
|
||||
#### Parameters
|
||||
statuses/friends_timeline
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* 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.
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
### statuses/public_timeline
|
||||
#### Parameters
|
||||
statuses/public_timeline
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* 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.
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* trim_user
|
||||
|
||||
### statuses/show
|
||||
#### Parameters
|
||||
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
|
||||
### Unsupported parameters
|
||||
* include_my_retweet
|
||||
* trim_user
|
||||
|
||||
### statuses/retweet
|
||||
#### Parameters
|
||||
statuses/retweet
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* id: message number
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* trim_user
|
||||
|
||||
### statuses/destroy
|
||||
#### Parameters
|
||||
statuses/destroy
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* id: message number
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* trim_user
|
||||
|
||||
### statuses/mentions
|
||||
#### Parameters
|
||||
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
|
||||
### Unsupported parameters
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
### statuses/replies
|
||||
#### Parameters
|
||||
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
|
||||
### Unsupported parameters
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
### statuses/user_timeline
|
||||
#### Parameters
|
||||
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)
|
||||
|
|
@ -171,15 +199,17 @@ Please refer to the linked documentation for further information.
|
|||
* conversation_id: Shows all statuses of a given conversation.
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
### conversation/show
|
||||
conversation/show
|
||||
---
|
||||
|
||||
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
|
||||
|
||||
#### Parameters
|
||||
### Parameters
|
||||
* id: id of the post
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
|
|
@ -187,86 +217,105 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
|
|||
* max_id: maximum id
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
### favorites
|
||||
#### Parameters
|
||||
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
|
||||
### 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
|
||||
account/rate_limit_status
|
||||
---
|
||||
|
||||
### help/test
|
||||
help/test
|
||||
---
|
||||
|
||||
### statuses/friends
|
||||
statuses/friends
|
||||
---
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* user_id
|
||||
* screen_name
|
||||
* cursor
|
||||
|
||||
Friendica doesn't allow showing friends of other users.
|
||||
|
||||
### statuses/followers
|
||||
statuses/followers
|
||||
---
|
||||
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* user_id
|
||||
* screen_name
|
||||
* cursor
|
||||
|
||||
Friendica doesn't allow showing followers of other users.
|
||||
|
||||
### statusnet/config
|
||||
statusnet/config
|
||||
---
|
||||
|
||||
### statusnet/version
|
||||
statusnet/version
|
||||
---
|
||||
|
||||
### friends/ids
|
||||
#### Parameters
|
||||
friends/ids
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* user_id
|
||||
* screen_name
|
||||
* cursor
|
||||
|
||||
Friendica doesn't allow showing friends of other users.
|
||||
|
||||
### followers/ids
|
||||
#### Parameters
|
||||
followers/ids
|
||||
---
|
||||
|
||||
Parameters
|
||||
---
|
||||
|
||||
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* user_id
|
||||
* screen_name
|
||||
* cursor
|
||||
|
||||
Friendica doesn't allow showing followers of other users.
|
||||
|
||||
### direct_messages/new
|
||||
#### Parameters
|
||||
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
|
||||
direct_messages/conversation
|
||||
---
|
||||
|
||||
Shows all direct messages of a conversation
|
||||
#### Parameters
|
||||
### Parameters
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* 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"
|
||||
* uri: URI of the conversation
|
||||
|
||||
### direct_messages/all
|
||||
#### Parameters
|
||||
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
|
||||
direct_messages/sent
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* 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"
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
### direct_messages
|
||||
#### Parameters
|
||||
direct_messages
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* 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"
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* skip_status
|
||||
|
||||
### oauth/request_token
|
||||
#### Parameters
|
||||
oauth/request_token
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* oauth_callback
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* x_auth_access_type
|
||||
|
||||
### oauth/access_token
|
||||
#### Parameters
|
||||
oauth/access_token
|
||||
---
|
||||
|
||||
### Parameters
|
||||
* oauth_verifier
|
||||
|
||||
#### Unsupported parameters
|
||||
### Unsupported parameters
|
||||
* x_auth_password
|
||||
* x_auth_username
|
||||
* 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):
|
||||
* favorites/create
|
||||
* favorites/destroy
|
||||
|
|
@ -346,17 +407,24 @@ The following are things from the Twitter API also not implemented in StatusNet:
|
|||
* blocks/blocking
|
||||
* lists
|
||||
|
||||
## Usage Examples
|
||||
### BASH / cURL
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue