From e752d4138953f9fb7fb0b86827f1dc3c29e0481a Mon Sep 17 00:00:00 2001 From: fabrixxm Date: Mon, 28 Dec 2015 09:47:51 +0100 Subject: [PATCH] Update API docs --- doc/api.md | 285 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 239 insertions(+), 46 deletions(-) diff --git a/doc/api.md b/doc/api.md index 391d6c9eb9..303b7f67a9 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1,6 +1,6 @@ Implemented API calls === -The Friendica API aims to be compatible to the [GNU Social API](http://skilledtests.com/wiki/Twitter-compatible_API) and the [Twitter API](https://dev.twitter.com/rest/public). +The Friendica API aims to be compatible to the [GNU Social API](http://skilledtests.com/wiki/Twitter-compatible_API) and the [Twitter API](https://dev.twitter.com/rest/public). Please refer to the linked documentation for further information. @@ -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: +``` + + Specific error message + API path requested + HTTP error code + +``` + +--- ### 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. @@ -43,10 +75,11 @@ Unofficial Twitter command. It shows all direct answers (excluding the original * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* include_rts -* trim_user -* contributor_details +* include_rts +* trim_user +* contributor_details +--- ### direct_messages #### Parameters * count: Items per page (default: 20) @@ -57,8 +90,9 @@ Unofficial Twitter command. It shows all direct answers (excluding the original * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* skip_status +* 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,14 +112,16 @@ 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 +* 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/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) @@ -125,20 +166,143 @@ Favorites aren't displayed to other users, so "user_id" and "screen_name". So se #### Unsupported parameters * user_id * screen_name -* cursor +* cursor Friendica doesn't allow showing followers of other users. +--- +### friendica/activity/ +#### 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 +```true``` + +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": { + "": "url to image" + ... + }, + // if 'scale' is set + "datasize": "size in byte", + "data": "base64 encoded image data" + } +``` + +xml +``` + + photo id + date(YYYY-MM-GG HH:MM:SS) + date(YYYY-MM-GG HH:MM:SS) + photo title + photo description + album name + original file name + mime type + number + number + 1 if is profile 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 +``` + + + "url to thumb sized image" + + ... + +``` + +--- ### friends/ids #### Parameters * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) @@ -146,46 +310,54 @@ Returns a list of all photo resources of the logged in user. #### Unsupported parameters * user_id * screen_name -* cursor +* cursor Friendica doesn't allow showing friends of other users. +--- ### help/test +--- ### media/upload #### Parameters * media: image data +--- ### oauth/request_token #### Parameters -* oauth_callback +* oauth_callback #### Unsupported parameters -* x_auth_access_type +* x_auth_access_type +--- ### oauth/access_token #### Parameters -* oauth_verifier +* oauth_verifier #### Unsupported parameters -* x_auth_password -* x_auth_username -* x_auth_mode +* x_auth_password +* x_auth_username +* x_auth_mode +--- ### statuses/destroy #### Parameters * id: message number * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* trim_user +* 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) @@ -197,10 +369,11 @@ Friendica doesn't allow showing friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* include_rts -* trim_user -* contributor_details +* include_rts +* trim_user +* contributor_details +--- ### statuses/home_timeline #### Parameters * count: Items per page (default: 20) @@ -212,10 +385,11 @@ Friendica doesn't allow showing friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* include_rts -* trim_user -* contributor_details +* include_rts +* trim_user +* contributor_details +--- ### statuses/mentions #### Parameters * count: Items per page (default: 20) @@ -225,10 +399,11 @@ Friendica doesn't allow showing friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* include_rts -* trim_user -* contributor_details +* include_rts +* trim_user +* contributor_details +--- ### statuses/public_timeline #### Parameters * count: Items per page (default: 20) @@ -240,8 +415,9 @@ Friendica doesn't allow showing friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* trim_user +* trim_user +--- ### statuses/replies #### Parameters * count: Items per page (default: 20) @@ -251,18 +427,20 @@ Friendica doesn't allow showing friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* include_rts -* trim_user -* contributor_details +* include_rts +* trim_user +* contributor_details +--- ### statuses/retweet #### Parameters * id: message number * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* trim_user +* trim_user +--- ### statuses/show #### Parameters * id: message number @@ -270,9 +448,10 @@ Friendica doesn't allow showing friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* include_my_retweet -* trim_user +* include_my_retweet +* trim_user +--- ### statuses/update, statuses/update_with_media #### Parameters * title: Title of the status @@ -289,16 +468,17 @@ Friendica doesn't allow showing friends of other users. * contact_deny * network * include_entities: "true" shows entities for pictures and links (Default: false) -* media_ids: (By now only a single value, no array) +* media_ids: (By now only a single value, no array) #### Unsupported parameters * trim_user * place_id * display_coordinates +--- ### statuses/user_timeline #### Parameters -* user_id: id of the user +* 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 @@ -309,46 +489,51 @@ Friendica doesn't allow showing friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters -* include_rts -* trim_user -* contributor_details +* include_rts +* trim_user +* contributor_details +--- ### statusnet/config +--- ### statusnet/version #### Unsupported parameters * user_id * screen_name -* cursor +* cursor Friendica doesn't allow showing followers of other users. +--- ### users/search #### Parameters -* q: name of the user +* q: name of the user #### Unsupported parameters * page * count * include_entities +--- ### users/show #### Parameters -* user_id: id of the user +* 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) #### Unsupported parameters * user_id * screen_name -* cursor +* cursor 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,12 +547,14 @@ 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 +* name: name of the group to be deleted #### Return values Array of: @@ -378,8 +565,9 @@ Array of: * wrong users: empty array +--- ### friendica/group_create -Create the group with the posted array of contacts as members. +Create the group with the posted array of contacts as members. #### Parameters * name: name of the group to be created @@ -395,11 +583,12 @@ Array of: * gid: gid of the created group * name: name of the created group * status: „missing user“ | „reactivated“ | „ok“ -* wrong users: array of users, which were not available in the contact table +* 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). +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 * gid: id of the group to be changed * name: name of the group to be changed @@ -416,9 +605,9 @@ Array of: * gid: gid of the changed group * name: name of the changed group * status: „missing user“ | „ok“ -* wrong users: array of users, which were not available in the contact table - +* 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)).