put all the api related stuff in the api folder

4 files changed, 426 insertions, 0 deletions

diff --git a/doc/api/api_functions.bb b/doc/api/api_functions.bb
new file mode 100644
index 000000000..e6cde3dc6
--- /dev/null
+++ b/doc/api/api_functions.bb
@@ -0,0 +1,133 @@
+[b]Red Twitter API[/b]

+

+The "basic" Red web API is based on the Twitter API, as this provides instant compatibility with a huge number of third-party clients and applications without requiring any code changes on their part. It is also a super-set of the StatusNet version of the Twitter API, as this also has existing wide support.

+

+Red has a lot more capability that isn't exposed in the Twitter interfaces or where we are forced to "dumb-down" the API functions to work with the primitive Twitter/StatusNet communications and privacy model. So we plan to extend the Twitter API in ways that will allow Red-specific clients to make full use of Red features without being crippled.

+

+A dedicated Red API is also being developed to work with native data structures and permissions and which do not require translating to different privacy and permission models and storage formats. This will be described in other documents. The prefix for all of the native endpoints is 'api/red'.

+

+Red provides multiple channels accesible via the same login account. With Red, any API function which requires authentication will accept a parameter &channel={channel_nickname} - and will select that channel and make it current before executing the API command. By default, the default channel associated with an account is selected.

+

+Red also provides an extended permission model. In the absence of any Red specific API calls to set permissions, they will be set to the default permissions settings which are associated with the current channel.

+

+Red will probably never be able to support the Twitter 'api/friendships' functions fully because Red is not a social network and has no concept of "friendships" - it only recognises permissions to do stuff (or not do stuff as the case may be).

+

+Legend: T= Twitter, S= StatusNet, F= Friendica, R= Red, ()=Not yet working, J= JSON only (XML formats deprecated)

+

+Twitter API compatible functions:

+

+    api/account/verify_credentials T,S,F,R

+    api/statuses/update T,S,F,R

+    api/users/show T,S,F,R

+    api/statuses/home_timeline T,S,F,R

+    api/statuses/friends_timeline T,S,F,R

+    api/statuses/public_timeline T,S,F,R

+    api/statuses/show T,S,F,R

+    api/statuses/retweet T,S,F,R

+    api/statuses/destroy T,S,F,(R)

+    api/statuses/mentions T,S,F,(R)

+    api/statuses/replies T,S,F,(R)

+    api/statuses/user_timeline T,S,F,(R)

+    api/favorites T,S,F,R

+    api/account/rate_limit_status T,S,F,R

+    api/help/test T,S,F,R

+    api/statuses/friends T,S,F,R

+    api/statuses/followers T,S,F,R

+    api/friends/ids T,S,F,R

+    api/followers/ids T,S,F,R

+    api/direct_messages/new T,S,F,R

+    api/direct_messages/conversation T,S,F,R

+    api/direct_messages/all T,S,F,R

+    api/direct_messages/sent T,S,F,R

+    api/direct_messages T,S,F,R

+    api/oauth/request_token T,S,F,R

+    api/oauth/access_token T,S,F,R

+    api/favorites T,S,R

+    api/favorites/create T,S,R

+    api/favorites/destroy T,S,R

+

+Twitter API functions supported by StatusNet but not currently by Friendica or Red

+

+    api/statuses/retweets_of_me T,S

+    api/friendships/create T,S

+    api/friendships/destroy T,S

+    api/friendships/exists T,S

+    api/friendships/show T,S

+    api/account/update_location T,S

+    api/account/update_profile_background_image T,S

+    api/account/update_profile_image T,S

+    api/blocks/create T,S

+    api/blocks/destroy T,S

+

+Twitter API functions not currently supported by StatusNet

+

+    api/statuses/retweeted_to_me T

+    api/statuses/retweeted_by_me T

+    api/direct_messages/destroy T

+    api/account/end_session T,(R)

+    api/account/update_delivery_device T

+    api/notifications/follow T

+    api/notifications/leave T

+    api/blocks/exists T

+    api/blocks/blocking T

+    api/lists T

+

+Statusnet compatible extensions to the Twitter API supported in both Friendica and Red

+

+    api/statusnet/version S,F,R

+    api/statusnet/config S,F,R

+

+Friendica API extensions to the Twitter API supported in both Friendica and Red

+

+    api/statuses/mediap F,R

+

+Red specific API extensions to the Twitter API not supported in Friendica

+

+    api/account/logout R

+    api/export/basic R,J

+    api/friendica/config R

+    api/red/config R

+    api/friendica/version R

+

+    api/red/version R

+

+    api/red/channel/export/basic R,J

+    api/red/channel/stream R,J (currently post only)

+    api/red/albums R,J

+    api/red/photos R,J (option album=xxxx)

+

+Red proposed API extensions to the Twitter API

+

+    api/statuses/edit (R),J

+    api/statuses/permissions (R),J

+    api/statuses/permissions/update (R),J

+    api/statuses/ids (R),J # search for existing message_id before importing a foreign post

+    api/files/show (R),J

+    api/files/destroy (R),J

+    api/files/update (R),J

+    api/files/permissions (R),J

+    api/files/permissions/update (R),J

+    api/pages/show (R),J

+    api/pages/destroy (R),J

+    api/pages/update (R),J

+    api/pages/permissions (R),J

+    api/pages/permissions/update (R),J

+    api/events/show (R),J

+    api/events/update (R),J

+    api/events/permissions (R),J

+    api/events/permissions/update (R),J

+    api/events/destroy (R),J

+    api/photos/show (R),J

+    api/photos/update (R),J

+    api/photos/permissions (R),J

+    api/photos/permissions/update (R),J

+    api/albums/destroy (R),J

+    api/albums/show (R),J

+    api/albums/update (R),J

+    api/albums/permissions (R),J

+    api/albums/permissions/update (R),J

+    api/albums/destroy (R),J

+    api/friends/permissions (R),J

+

+#include doc/macros/main_footer.bb;

+

diff --git a/doc/api/api_item_update.md b/doc/api/api_item_update.md
new file mode 100644
index 000000000..598fd114a
--- /dev/null
+++ b/doc/api/api_item_update.md
@@ -0,0 +1,225 @@
+API item/update
+===============
+
+
+Usage: POST /api/z/1.0/item/update
+
+Description: item/update posts an item (typically a conversation item or post, but can be any item) using form input.  
+
+
+Required:
+
+- body
+
+	text/bbcode contents by default.
+
+
+Optional:
+
+- $_FILES['media']
+
+	uploaded media file to include with post
+
+- title
+
+	title of post/item
+
+- contact_allow
+
+	array of xchan.xchan_hash allowed to view this item
+
+- group_allow
+
+	array of group.hash allowed to view this item
+
+- contact_deny
+
+	array of xchan.xchan_hash not allowed to view this item
+
+- group_deny
+
+	array of group.hash not allowed to view this item
+
+- coord
+
+	geographic coordinates
+
+- location
+
+	freefrom location
+
+- expire
+
+	datetime this post will expire or be removed
+
+- mimetype
+
+	mimetype if not text/bbcode
+
+- parent
+
+	item.id of parent to this post (makes it a comment)
+
+- parent_mid
+
+	alternate form of parent using message_id
+
+- remote_xchan
+
+	xchan.xchan_hash of this message author if not the channel owner
+
+- consensus
+
+	boolean set to true if this is a consensus or voting item (default false)
+
+- nocomment
+
+	boolean set to true if comments are to be disabled (default false)
+
+- origin
+
+	do not use this without reading the code
+
+- namespace
+
+	persistent identity for a remote network or service
+
+- remote_id
+
+	message_id of this resource on a remote network or service
+
+- message_id
+
+	message_id of this item (leave unset to generate one)
+
+- created
+
+	datetime of message creation
+
+- post_id
+
+	existing item.id if this is an edit operation
+
+- app
+
+	application or network name to display with item
+
+- categories
+
+	comma separated categories for this item
+
+- webpage
+
+	item.page_type if not 0
+
+- pagetitle
+
+	for webpage and design elements, the 'page name'
+
+- layout_mid
+
+	item.mid of layout for this design element
+
+- plink
+
+	permalink for this item if different than the default
+
+- verb
+
+	activitystream verb for this item/activity
+
+- obj_type
+
+	activitystream object type for this item/activity
+
+
+
+Example: 
+
+curl -u mychannel:mypassword https://xyz.macgirvin.com/api/z/1.0/item/update -d body="hello world"
+
+
+Returns:
+
+
+	{
+	
+	    "success": true,
+	    "item_id": "2245",
+	    "item": {
+	        "id": "2245",
+	        "mid": "14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com",
+	        "aid": "1",
+	        "uid": "2",
+	        "parent": "0",
+		        "parent_mid": "14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com",
+	        "thr_parent": "14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com",
+	        "created": "2016-12-03 20:00:12",
+	        "edited": "2016-12-03 20:00:12",
+	        "expires": "0001-01-01 00:00:00",
+	        "commented": "2016-12-03 20:00:12",
+	        "received": "2016-12-03 20:00:12",
+	        "changed": "2016-12-03 20:00:12",
+	        "comments_closed": "0001-01-01 00:00:00",
+	        "owner_xchan": "pgcJx1IQjuPkx8aI9qheJlBMZzJz-oTPjHy3h5pWlOVOriBO_cSiUhhqwhuZ74TYJ8_ECO3pPiRMWC0q8YPCQg",
+	        "author_xchan": "pgcJx1IQjuPkx8aI9qheJlBMZzJz-oTPjHy3h5pWlOVOriBO_cSiUhhqwhuZ74TYJ8_ECO3pPiRMWC0q8YPCQg",
+	        "source_xchan": "",
+	        "mimetype": "text/bbcode",
+	        "title": "",
+	        "body": "hello world",
+	        "html": "",
+	        "app": "",
+	        "lang": "",
+	        "revision": "0",
+	        "verb": "http://activitystrea.ms/schema/1.0/post",
+	        "obj_type": "http://activitystrea.ms/schema/1.0/note",
+	        "obj": "",
+	        "tgt_type": "",
+	        "target": "",
+	        "layout_mid": "",
+	        "postopts": "",
+	        "route": "",
+	        "llink": "https://xyz.macgirvin.com/display/14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com",
+	        "plink": "https://xyz.macgirvin.com/channel/mychannel/?f=&mid=14135cdecf6b8e3891224e4391748722114da6668eebbcb56fe4667b60b88249@xyz.macgirvin.com",
+	        "resource_id": "",
+	        "resource_type": "",
+	        "attach": "",
+	        "sig": "sa4TOQNfHtV13HDZ1tuQGWNBpZp-nWhT2GMrZEmelXxa_IvEepD2SEsCTWOBqM8OKPJLfNy8_i-ORXjrOIIgAa_aT8cw5vka7Q0C8L9eEb_LegwQ_BtH0CXO5uT30e_8uowkwzh6kmlVg1ntD8QqrGgD5jTET_fMQOIw4gQUBh40GDG9RB4QnPp_MKsgemGrADnRk2vHO7-bR32yQ0JI-8G-eyeqGaaJmIwkHoi0vXsfjZtU7ijSLuKEBWboNjKEDU89-vQ1c5Kh1r0pmjiDk-a5JzZTYShpuhVA-vQgEcADA7wkf4lJZCYNwu3FRwHTvhSMdF0nmyv3aPFglQDky38-SAXZyQSvd7qlABHGCVVDmYrYaiq7Dh4rRENbAUf-UJFHPCVB7NRg34R8HIqmOKq1Su99bIWaoI2zuAQEVma9wLqMoFsluFhxX58KeVtlCZlro7tZ6z619-dthS_fwt0cL_2dZ3QwjG1P36Q4Y4KrCTpntn9ot5osh-HjVQ01h1I9yNCj6XPgYJ8Im3KT_G4hmMDFM7H9RUrYLl2o9XYyiS2nRrf4aJHa0UweBlAY4zcQG34bw2AMGCY53mwsSArf4Hs3rKu5GrGphuwYX0lHa7XEKMglwBWPWHI49q7-oNWr7aWwn1FnfaMfl4cQppCMtKESMNRKm_nb9Dsh5e0",
+	        "diaspora_meta": "",
+	        "location": "",
+	        "coord": "",
+	        "public_policy": "",
+	        "comment_policy": "contacts",
+	        "allow_cid": "",
+	        "allow_gid": "",
+	        "deny_cid": "",
+	        "deny_gid": "",
+	        "item_restrict": "0",
+	        "item_flags": "0",
+	        "item_private": "0",
+	        "item_origin": "1",
+	        "item_unseen": "0",
+	        "item_starred": "0",
+	        "item_uplink": "0",
+	        "item_consensus": "0",
+	        "item_wall": "1",
+	        "item_thread_top": "1",
+	        "item_notshown": "0",
+	        "item_nsfw": "0",
+	        "item_relay": "0",
+	        "item_mentionsme": "0",
+	        "item_nocomment": "0",
+	        "item_obscured": "0",
+	        "item_verified": "1",
+	        "item_retained": "0",
+	        "item_rss": "0",
+	        "item_deleted": "0",
+	        "item_type": "0",
+	        "item_hidden": "0",
+	        "item_unpublished": "0",
+	        "item_delayed": "0",
+	        "item_pending_remove": "0",
+	        "item_blocked": "0"
+	    }
+
+	}
\ No newline at end of file
diff --git a/doc/api/api_posting.bb b/doc/api/api_posting.bb
new file mode 100644
index 000000000..c708ad143
--- /dev/null
+++ b/doc/api/api_posting.bb
@@ -0,0 +1,24 @@
+[b][size=xx-large]Posting to the Matrix via the API[/size][/b]
+
+The API allows you to post to the red# by HTTP POST request. Below you see an example using the command line tool cURL:
+
+[code]curl -ssl -u [color=blue]$E-Mail[/color]:[color=blue]$Password[/color] -d "[color=blue]$Parameters[/color]" [url][observer=1][observer.baseurl][/observer][observer=0]example.com[/observer]/api/statuses/update
+[/url][/code]
+[table][tr][td]$E-Mail:[/td][td]The E-Mail Address you use to login, or the channel nickname (without the hostname)[/td][/tr]
+[tr][td]$Password:[/td][td]The Password you use to login[/td][/tr]
+[tr][td]$Parameters:[/td][td]That's the interesting part, here you insert the content you want to send using the following parameters:[/td][/tr][/table]
+
+[ul]
+[*]title: the title of the posting
+[*]channel: the channel you want to post to (do not use this parameter with HTTP Basic auth)
+[*]category: a comma-seperated list of categories for the posting
+[*]status: the content of the posting, formatted with BBCode
+                                OR
+[*]htmlstatus:the content of the posting, formatted in HTML.
+[/ul]
+
+To post to a specific channel, replace the email address with the channel nickname. If you supply the channel parameter, it has to match the "email", but is superfluous anyway.
+
+Instead of calling [observer=1][observer.baseurl][/observer][observer=0]example.com[/observer]/api/statuses/update which returns a json (you could also add .json on the end to clarify) output, you can use [observer.baseurl]/api/statuses/update.xml to get an xml formatted return.
+
+Instead of Basic HTTP Authentification you could also use oAuth.
diff --git a/doc/api/api_xchan.md b/doc/api/api_xchan.md
new file mode 100644
index 000000000..d2b15e04c
--- /dev/null
+++ b/doc/api/api_xchan.md
@@ -0,0 +1,44 @@
+API xchan
+=========
+
+An xchan is a global location independent channel and is the primary record for a network 
+identity. It may refer to channels on other websites, networks, or services. 
+
+GET /api/z/1.0/xchan
+
+Required: one of [ address, hash, guid ] as GET parameters
+
+Returns a portable xchan structure
+
+Example: https://xyz.macgirvin.com/api/z/1.0/xchan?f=&address=mike@macgirvin.com
+
+Returns:
+
+	{
+        "hash": "jr54M_y2l5NgHX5wBvP0KqWcAHuW23p1ld-6Vn63_pGTZklrI36LF8vUHMSKJMD8xzzkz7s2xxCx4-BOLNPaVA",
+        "guid": "sebQ-IC4rmFn9d9iu17m4BXO-kHuNutWo2ySjeV2SIW1LzksUkss12xVo3m3fykYxN5HMcc7gUZVYv26asx-Pg",
+        "guid_sig": "Llenlbl4zHo6-g4sa63MlQmTP5dRCrsPmXHHFmoCHG63BLq5CUZJRLS1vRrrr_MNxr7zob_Ykt_m5xPKe5H0_i4pDj-UdP8dPZqH2fqhhx00kuYL4YUMJ8gRr5eO17vsZQ3XxTcyKewtgeW0j7ytwMp6-hFVUx_Cq08MrXas429ZrjzaEwgTfxGnbgeQYQ0R5EXpHpEmoERnZx77VaEahftmdjAUx9R4YKAp13pGYadJOX5xnLfqofHQD8DyRHWeMJ4G1OfWPSOlXfRayrV_jhnFlZjMU7vOdQwHoCMoR5TFsRsHuzd-qepbvo3pzvQZRWnTNu6oPucgbf94p13QbalYRpBXKOxdTXJrGdESNhGvhtaZnpT9c1QVqC46jdfP0LOX2xrVdbvvG2JMWFv7XJUVjLSk_yjzY6or2VD4V6ztYcjpCi9d_WoNHruoxro_br1YO3KatySxJs-LQ7SOkQI60FpysfbphNyvYMkotwUFI59G08IGKTMu3-GPnV1wp7NOQD1yzJbGGEGSEEysmEP0SO9vnN45kp3MiqbffBGc1r4_YM4e7DPmqOGM94qksOcLOJk1HNESw2dQYWxWQTBXPfOJT6jW9_crGLMEOsZ3Jcss0XS9KzBUA2p_9osvvhUKuKXbNztqH0oZIWlg37FEVsDs_hUwUJpv2Ar09k4",
+        "pubkey": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA7QCwvuEIwCHjhjbpz3Oc\ntyei/Pz9nDksNbsc44Cm8jxYGMXsTPFXDZYCcCB5rcAhPPdZSlzaPkv4vPVcMIrw\n5cdX0tvbwa3rNTng6uFE7qkt15D3YCTkwF0Y9FVZiZ2Ko+G23QeBt9wqb9dlDN1d\nuPmu9BLYXIT/JXoBwf0vjIPFM9WBi5W/EHGaiuqw7lt0qI7zDGw77yO5yehKE4cu\n7dt3SakrXphL70LGiZh2XGoLg9Gmpz98t+gvPAUEotAJxIUqnoiTA8jlxoiQjeRK\nHlJkwMOGmRNPS33awPos0kcSxAywuBbh2X3aSqUMjcbE4cGJ++/13zoa6RUZRObC\nZnaLYJxqYBh13/N8SfH7d005hecDxWnoYXeYuuMeT3a2hV0J84ztkJX5OoxIwk7S\nWmvBq4+m66usn6LNL+p5IAcs93KbvOxxrjtQrzohBXc6+elfLVSQ1Rr9g5xbgpub\npSc+hvzbB6p0tleDRzwAy9X16NI4DYiTj4nkmVjigNo9v2VPnAle5zSam86eiYLO\nt2u9YRqysMLPKevNdj3CIvst+BaGGQONlQalRdIcq8Lin+BhuX+1TBgqyav4XD9K\nd+JHMb1aBk/rFLI9/f2S3BJ1XqpbjXz7AbYlaCwKiJ836+HS8PmLKxwVOnpLMbfH\nPYM8k83Lip4bEKIyAuf02qkCAwEAAQ==\n-----END PUBLIC KEY-----\n",
+        "photo_mimetype": "image/jpeg",
+        "photo_l": "https://xyz.macgirvin.com/photo/350b74555c04429148f2e12775f6c403-4",
+        "photo_m": "https://xyz.macgirvin.com/photo/350b74555c04429148f2e12775f6c403-5",
+        "photo_s": "https://xyz.macgirvin.com/photo/350b74555c04429148f2e12775f6c403-6",
+        "address": "mike@macgirvin.com",
+        "url": "https://macgirvin.com/channel/mike",
+        "connurl": "https://macgirvin.com/poco/mike",
+        "follow": "https://macgirvin.com/follow?f=&url=%s",
+        "connpage": "https://macgirvin.com/connect/mike",
+        "name": "Mike Macgirvin",
+        "network": "zot",
+        "instance_url": "",
+        "flags": "0",
+        "photo_date": "2012-12-06 05:06:11",
+        "name_date": "2012-12-06 04:59:13",
+        "hidden": "1",
+        "orphan": "0",
+        "censored": "0",
+        "selfcensored": "0",
+        "system": "0",
+        "pubforum": "0",
+        "deleted": "0"
+	}
\ No newline at end of file