Update API docs

doc/api.md

@@ -24,13 +24,45 @@ Please refer to the linked documentation for further information.
 * cid: Contact id of the user (important for "contact_allow" and "contact_deny")
 * network: network of the user
 
+#### Errors
+When an error occour in API call, an HTTP error code is returned, with an error message
+Usually:
+- 400 Bad Request: if parameter are missing or items can't be found
+- 403 Forbidden: if authenticated user is missing
+- 405 Method Not Allowed: if API was called with invalid method, eg. GET when API require POST
+- 501 Not Implemented: if requested API doesn't exists
+- 500 Internal Server Error: on other error contitions
+
+Error body is
+
+json:
+```
+	{
+	  "error": "Specific error message",
+	  "request": "API path requested",
+	  "code": "HTTP error code"
+	}
+```
+
+xml:
+```
+	<status>
+		<error>Specific error message</error>
+		<request>API path requested</request>
+		<code>HTTP error code</code>
+	</status>
+```
+
+---
 ### account/rate_limit_status
 
+---
 ### 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)
 
+---
 ### conversation/show
 Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
 
@@ -47,6 +79,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
 * trim_user
 * contributor_details
 
+---
 ### direct_messages
 #### Parameters
 * count: Items per page (default: 20)
@@ -59,6 +92,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
 #### Unsupported parameters
 * skip_status
 
+---
 ### direct_messages/all
 #### Parameters
 * count: Items per page (default: 20)
@@ -67,6 +101,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
 * max_id: maximum id
 * getText: Defines the format of the status field. Can be "html" or "plain"
 
+---
 ### direct_messages/conversation
 Shows all direct messages of a conversation
 #### Parameters
@@ -77,6 +112,7 @@ 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/new
 #### Parameters
 * user_id: id of the user
@@ -85,6 +121,7 @@ Shows all direct messages of a conversation
 * replyto: ID of the replied direct message
 * title: Title of the direct message
 
+---
 ### direct_messages/sent
 #### Parameters
 * count: Items per page (default: 20)
@@ -94,6 +131,7 @@ 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)
 
+---
 ### favorites
 #### Parameters
 * count: Items per page (default: 20)
@@ -108,16 +146,19 @@ Shows all direct messages of a conversation
 
 Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array.
 
+---
 ### favorites/create
 #### Parameters
 * id
 * include_entities: "true" shows entities for pictures and links (Default: false)
 
+---
 ### favorites/destroy
 #### Parameters
 * id
 * include_entities: "true" shows entities for pictures and links (Default: false)
 
+---
 ### followers/ids
 #### Parameters
 * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
@@ -129,16 +170,139 @@ Favorites aren't displayed to other users, so "user_id" and "screen_name". So se
 
 Friendica doesn't allow showing followers of other users.
 
+---
+### friendica/activity/<verb>
+#### parameters
+* id: item id
+
+Add or remove an activity from an item.
+'verb' can be one of:
+- like
+- dislike
+- attendyes
+- attendno
+- attendmaybe
+
+To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
+Attend verbs disable eachother: that means that if "attendyes" was added to an item,
+adding "attendno" remove previous "attendyes".
+Attend verbs should be used only with event-related items (there is no check at the moment)
+
+#### Return values
+
+On success:
+json
+```"ok"```
+
+xml
+```<ok>true</ok>```
+
+On error:
+HTTP 400 BadRequest
+
+---
 ### friendica/photo
 #### Parameters
 * photo_id: Resource id of a photo.
+* scale: (optional) scale value of the photo
 
 Returns data of a picture with the given resource.
+If 'scale' isn't provided, returned data include full url to each scale of the photo.
+If 'scale' is set, returned data include image data base64 encoded.
+
+possibile scale value are:
+0: original or max size by server settings
+1: image with or height at <= 640
+2: image with or height at <= 320
+3: thumbnail 160x160
+
+4: Profile image at 175x175
+5: Profile image at 80x80
+6: Profile image at 48x48
+
+An image used as profile image has only scale 4-6, other images only 0-3
+
+#### Return values
+
+json
+```
+	{
+	  "id": "photo id"
+	  "created": "date(YYYY-MM-GG HH:MM:SS)",
+	  "edited": "date(YYYY-MM-GG HH:MM:SS)",
+	  "title": "photo title",
+	  "desc": "photo description",
+	  "album": "album name",
+	  "filename": "original file name",
+	  "type": "mime type",
+	  "height": "number",
+	  "width": "number",
+	  "profile": "1 if is profile photo",
+	  "link": {
+		"<scale>": "url to image"
+		...
+	  },
+	  // if 'scale' is set
+	  "datasize": "size in byte",
+	  "data": "base64 encoded image data"
+	}
+```
+
+xml
+```
+	<photo>
+		<id>photo id</id>
+		<created>date(YYYY-MM-GG HH:MM:SS)</created>
+		<edited>date(YYYY-MM-GG HH:MM:SS)</edited>
+		<title>photo title</title>
+		<desc>photo description</desc>
+		<album>album name</album>
+		<filename>original file name</filename>
+		<type>mime type</type>
+		<height>number</height>
+		<width>number</width>
+		<profile>1 if is profile photo</profile>
+		<links type="array">
+			<link type="mime type" scale="scale number" href="image url"/>
+			...
+		</links>
+	</photo>
+```
 
 ### friendica/photos/list
 
 Returns a list of all photo resources of the logged in user.
 
+#### Return values
+
+json
+```
+	[
+		{
+			id: "resource_id",
+			album: "album name",
+			filename: "original file name",
+			type: "image mime type",
+			thumb: "url to thumb sized image"
+		},
+		...
+	]
+```
+
+xml
+```
+	<photos type="array">
+		<photo id="resource_id"
+			album="album name"
+			filename="original file name"
+			type="image mime type">
+				"url to thumb sized image"
+		</photo>
+		...
+	</photos>
+```
+
+---
 ### friends/ids
 #### Parameters
 * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
@@ -150,12 +314,15 @@ Returns a list of all photo resources of the logged in user.
 
 Friendica doesn't allow showing friends of other users.
 
+---
 ### help/test
 
+---
 ### media/upload
 #### Parameters
 * media: image data
 
+---
 ### oauth/request_token
 #### Parameters
 * oauth_callback
@@ -163,6 +330,7 @@ Friendica doesn't allow showing friends of other users.
 #### Unsupported parameters
 * x_auth_access_type
 
+---
 ### oauth/access_token
 #### Parameters
 * oauth_verifier
@@ -172,6 +340,7 @@ Friendica doesn't allow showing friends of other users.
 * x_auth_username
 * x_auth_mode
 
+---
 ### statuses/destroy
 #### Parameters
 * id: message number
@@ -180,12 +349,15 @@ Friendica doesn't allow showing friends of other users.
 #### Unsupported parameters
 * trim_user
 
+---
 ### statuses/followers
 * include_entities: "true" shows entities for pictures and links (Default: false)
 
+---
 ### statuses/friends
 * include_entities: "true" shows entities for pictures and links (Default: false)
 
+---
 ### statuses/friends_timeline
 #### Parameters
 * count: Items per page (default: 20)
@@ -201,6 +373,7 @@ Friendica doesn't allow showing friends of other users.
 * trim_user
 * contributor_details
 
+---
 ### statuses/home_timeline
 #### Parameters
 * count: Items per page (default: 20)
@@ -216,6 +389,7 @@ Friendica doesn't allow showing friends of other users.
 * trim_user
 * contributor_details
 
+---
 ### statuses/mentions
 #### Parameters
 * count: Items per page (default: 20)
@@ -229,6 +403,7 @@ Friendica doesn't allow showing friends of other users.
 * trim_user
 * contributor_details
 
+---
 ### statuses/public_timeline
 #### Parameters
 * count: Items per page (default: 20)
@@ -242,6 +417,7 @@ Friendica doesn't allow showing friends of other users.
 #### Unsupported parameters
 * trim_user
 
+---
 ### statuses/replies
 #### Parameters
 * count: Items per page (default: 20)
@@ -255,6 +431,7 @@ Friendica doesn't allow showing friends of other users.
 * trim_user
 * contributor_details
 
+---
 ### statuses/retweet
 #### Parameters
 * id: message number
@@ -263,6 +440,7 @@ Friendica doesn't allow showing friends of other users.
 #### Unsupported parameters
 * trim_user
 
+---
 ### statuses/show
 #### Parameters
 * id: message number
@@ -273,6 +451,7 @@ Friendica doesn't allow showing friends of other users.
 * include_my_retweet
 * trim_user
 
+---
 ### statuses/update, statuses/update_with_media
 #### Parameters
 * title: Title of the status
@@ -296,6 +475,7 @@ Friendica doesn't allow showing friends of other users.
 * place_id
 * display_coordinates
 
+---
 ### statuses/user_timeline
 #### Parameters
 * user_id: id of the user
@@ -313,8 +493,10 @@ Friendica doesn't allow showing friends of other users.
 * trim_user
 * contributor_details
 
+---
 ### statusnet/config
 
+---
 ### statusnet/version
 
 #### Unsupported parameters
@@ -324,6 +506,7 @@ Friendica doesn't allow showing friends of other users.
 
 Friendica doesn't allow showing followers of other users.
 
+---
 ### users/search
 #### Parameters
 * q: name of the user
@@ -333,6 +516,7 @@ Friendica doesn't allow showing followers of other users.
 * count
 * include_entities
 
+---
 ### users/show
 #### Parameters
 * user_id: id of the user
@@ -349,6 +533,7 @@ Friendica doesn't allow showing friends of other users.
 
 ## Implemented API calls (not compatible with other APIs)
 
+---
 ### friendica/group_show
 Return all or a specified group of the user with the containing contacts as array.
 
@@ -362,9 +547,11 @@ Array of:
 * user: array of group members (return from api_get_user() function for each member)
 
 
+---
 ### friendica/group_delete
 delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
 
+---
 ### Parameters
 * gid: id of the group to be deleted
 * name: name of the group to be deleted
@@ -378,6 +565,7 @@ Array of:
 * wrong users: empty array
 
 
+---
 ### friendica/group_create
 Create the group with the posted array of contacts as members.
 #### Parameters
@@ -398,6 +586,7 @@ Array of:
 * wrong users: array of users, which were not available in the contact table
 
 
+---
 ### friendica/group_update
 Update the group with the posted array of contacts as members (post all members of the group to the call; function will remove members not posted).
 #### Parameters
@@ -418,7 +607,7 @@ Array of:
 * status: „missing user“ | „ok“
 * wrong users: array of users, which were not available in the contact table
 
-
+---
 ## Not Implemented API calls
 The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
 
@@ -505,6 +694,10 @@ The following API calls from the Twitter API aren't implemented neither in Frien
 * trends/closest
 * users/report_spam
 
+---
+
+---
+
 ## 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)).