From f4eaf5842d0a7615c7b9cb81f354cf60f37f7300 Mon Sep 17 00:00:00 2001
From: Silke Meyer <silke@silkemeyer.net>
Date: Fri, 17 Apr 2015 18:17:44 +0200
Subject: [PATCH] sorted out the headings' md syntax
---
doc/api.md | 238 ++++++++++++++++++++++++++++++++++-------------------
1 file changed, 153 insertions(+), 85 deletions(-)
diff --git a/doc/api.md b/doc/api.md
index f36a79a5eb..fa9df1245e 100644
--- a/doc/api.md
+++ b/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
+---
-### friends/ids
-#### Parameters
+### 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.
\ No newline at end of file
+There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.
--
2.39.5