From cf063b2045e3a541d1655df7ed6d3be13b539487 Mon Sep 17 00:00:00 2001 From: Pierre Rudloff Date: Tue, 19 Dec 2017 12:07:31 +0100 Subject: [PATCH] Lint doc/api.md --- doc/api.md | 304 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 259 insertions(+), 45 deletions(-) diff --git a/doc/api.md b/doc/api.md index 2896bd67b3..b61fb8aa66 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1,5 +1,6 @@ -Friendica API -=== +# Friendica API + + * [Home](help) @@ -10,6 +11,7 @@ Please refer to the linked documentation for further information. ## Implemented API calls ### General + #### HTTP Method API endpoints can restrict the method used to request them. @@ -26,6 +28,7 @@ OAuth settings can be added by the user in web UI under /settings/oauth/ In this document, endpoints which requires auth are marked with "AUTH" after endpoint name #### Unsupported parameters + * cursor: Not implemented in GNU Social * trim_user: Not implemented in GNU Social * contributor_details: Not implemented in GNU Social @@ -35,26 +38,31 @@ In this document, endpoints which requires auth are marked with "AUTH" after end * include_my_retweet: Retweets in Friendica are implemented in a different way #### 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 + * cid: Contact id of the user (important for "contact_allow" and "contact_deny") * network: network of the user #### Errors + When an error occurs in API call, an HTTP error code is returned, with an error message Usually: -- 400 Bad Request: if parameters are missing or items can't be found -- 403 Forbidden: if the authenticated user is missing -- 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST -- 501 Not Implemented: if the requested API doesn't exist -- 500 Internal Server Error: on other error conditions + +* 400 Bad Request: if parameters are missing or items can't be found +* 403 Forbidden: if the authenticated user is missing +* 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST +* 501 Not Implemented: if the requested API doesn't exist +* 500 Internal Server Error: on other error conditions Error body is json: -``` + +```json { "error": "Specific error message", "request": "API path requested", @@ -63,7 +71,8 @@ json: ``` xml: -``` + +```xml Specific error message API path requested @@ -72,20 +81,26 @@ xml: ``` --- + ### account/rate_limit_status (*; AUTH) --- + ### account/verify_credentials (*; AUTH) + #### Parameters * skip_status: Don't show the "status" field. (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false) --- + ### conversation/show (*; AUTH) + Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id. #### Parameter + * id: id of the post * count: Items per page (default: 20) * page: page number @@ -94,13 +109,17 @@ 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 --- + ### direct_messages (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -110,11 +129,15 @@ Unofficial Twitter command. It shows all direct answers (excluding the original * friendica_verbose: "true" enables different error returns (default: "false") #### Unsupported parameters + * skip_status --- + ### direct_messages/all (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -123,9 +146,13 @@ Unofficial Twitter command. It shows all direct answers (excluding the original * friendica_verbose: "true" enables different error returns (default: "false") --- + ### direct_messages/conversation (*; AUTH) + Shows all direct messages of a conversation + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -135,8 +162,11 @@ Shows all direct messages of a conversation * friendica_verbose: "true" enables different error returns (default: "false") --- + ### direct_messages/sent (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -146,8 +176,11 @@ Shows all direct messages of a conversation * friendica_verbose: "true" enables different error returns (default: "false") --- + ### direct_messages/new (POST,PUT; AUTH) + #### Parameters + * user_id: id of the user * screen_name: screen name (for technical reasons, this value is not unique!) * text: The message @@ -155,8 +188,11 @@ Shows all direct messages of a conversation * title: Title of the direct message --- + ### direct_messages/destroy (POST,DELETE; AUTH) + #### Parameters + * id: id of the message to be deleted * include_entities: optional, currently not yet implemented * friendica_parenturi: optional, can be used for increased safety to delete only intended messages @@ -165,21 +201,29 @@ Shows all direct messages of a conversation #### Return values On success: + * JSON return as defined for Twitter API not yet implemented * on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"} On error: HTTP 400 BadRequest + * on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"} --- + ### externalprofile/show (*) + #### Parameters + * profileurl: profile url --- + ### favorites (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -187,6 +231,7 @@ HTTP 400 BadRequest * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters + * user_id * screen_name @@ -194,23 +239,33 @@ Favorites aren't displayed to other users, so "user_id" and "screen_name" are un Set this values will result in an empty array. --- + ### favorites/create (POST,PUT; AUTH) + #### Parameters + * id * include_entities: "true" shows entities for pictures and links (Default: false) --- + ### favorites/destroy (POST,DELETE; AUTH) + #### Parameters + * id * include_entities: "true" shows entities for pictures and links (Default: false) --- + ### followers/ids (*; AUTH) + #### Parameters + * stringify_ids: Send id numbers as text (true) or integers (false)? (default: false) #### Unsupported parameters + * user_id * screen_name * cursor @@ -218,11 +273,15 @@ Set this values will result in an empty array. Friendica doesn't allow showing the followers of other users. --- + ### friends/ids (*; AUTH) + #### Parameters + * stringify_ids: Send the id numbers as text (true) or integers (false)? (default: false) #### Unsupported parameters + * user_id * screen_name * cursor @@ -230,41 +289,58 @@ Friendica doesn't allow showing the followers of other users. Friendica doesn't allow showing the friends of other users. --- + ### help/test (*) --- + ### media/upload (POST,PUT; AUTH) + #### Parameters + * media: image data --- + ### oauth/request_token (*) + #### Parameters + * oauth_callback #### Unsupported parameters + * x_auth_access_type --- + ### oauth/access_token (*) + #### Parameters + * oauth_verifier #### Unsupported parameters + * x_auth_password * x_auth_username * x_auth_mode --- + ### statuses/destroy (POST,DELETE; AUTH) + #### Parameters + * id: message number * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters + * trim_user --- + ### statuses/followers (*; AUTH) #### Parameters @@ -272,6 +348,7 @@ Friendica doesn't allow showing the friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) --- + ### statuses/friends (*; AUTH) #### Parameters @@ -279,6 +356,7 @@ Friendica doesn't allow showing the friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) --- + ### blocks/list (*; AUTH) #### Parameters @@ -288,12 +366,16 @@ Friendica doesn't allow showing the friends of other users. * page: page number #### Unsupported parameters + * cursor * skip_status --- + ### statuses/friends_timeline (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -303,13 +385,17 @@ Friendica doesn't allow showing the friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters + * include_rts * trim_user * contributor_details --- + ### statuses/home_timeline (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -319,13 +405,17 @@ Friendica doesn't allow showing the friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters + * include_rts * trim_user * contributor_details --- + ### statuses/mentions (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -333,13 +423,17 @@ Friendica doesn't allow showing the friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters + * include_rts * trim_user * contributor_details --- + ### statuses/public_timeline (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -349,11 +443,15 @@ Friendica doesn't allow showing the friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters + * trim_user --- + ### statuses/networkpublic_timeline (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -361,8 +459,11 @@ Friendica doesn't allow showing the friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) --- + ### statuses/replies (*; AUTH) + #### Parameters + * count: Items per page (default: 20) * page: page number * since_id: minimum id @@ -370,33 +471,45 @@ Friendica doesn't allow showing the friends of other users. * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters + * include_rts * trim_user * contributor_details --- + ### statuses/retweet (POST,PUT; AUTH) + #### Parameters + * id: message number * include_entities: "true" shows entities for pictures and links (Default: false) #### Unsupported parameters + * trim_user --- + ### statuses/show (*; AUTH) + #### 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 + * include_my_retweet * trim_user --- + ### statuses/update, statuses/update_with_media + #### Parameters + * title: Title of the status * status: Status in text format * htmlstatus: Status in HTML format @@ -414,13 +527,17 @@ Friendica doesn't allow showing the friends of other users. * media_ids: (By now only a single value, no array) #### Unsupported parameters + * trim_user * place_id * display_coordinates --- + ### statuses/user_timeline (*; AUTH) + #### 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) @@ -438,13 +555,17 @@ Friendica doesn't allow showing the friends of other users. * contributor_details --- + ### statusnet/config (*) --- + ### statusnet/conversation (*; AUTH) + It shows all direct answers (excluding the original post) to a given id. #### Parameter + * id: id of the post * count: Items per page (default: 20) * page: page number @@ -453,9 +574,11 @@ It shows all direct answers (excluding the original post) to a given id. * include_entities: "true" shows entities for pictures and links (Default: false) --- + ### statusnet/version (*) #### Unsupported parameters + * user_id * screen_name * cursor @@ -463,8 +586,11 @@ It shows all direct answers (excluding the original post) to a given id. Friendica doesn't allow showing followers of other users. --- + ### search (*; AUTH) + #### Parameters + * q: search query * page: the page number (starting at 1) to return * rpp: the number of statuses to return per page @@ -473,6 +599,7 @@ Friendica doesn't allow showing followers of other users. * max_id: returns statuses with ids lower or equal to the given id #### Unsupported parameters + * geocode * lang * locale @@ -481,23 +608,31 @@ Friendica doesn't allow showing followers of other users. * include_entities --- + ### users/search (*) + #### Parameters + * q: name of the user #### Unsupported parameters + * page * count * include_entities --- + ### 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) #### Unsupported parameters + * user_id * screen_name * cursor @@ -505,18 +640,24 @@ Friendica doesn't allow showing followers of other users. Friendica doesn't allow showing friends of other users. --- + ### users/lookup (*; AUTH) #### Parameters + * user_id: list of ids to lookup #### Unsupported parameters + * screen_name * include_entities --- + ### account/update_profile_image (POST; AUTH) + #### Parameters + * image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more) * profile_id (optional): id of the profile for which the image should be used, default is changing the default profile @@ -525,9 +666,11 @@ uploads a new profile image (scales 4-6) to database, changes default or specifi #### Return values On success: + * JSON return: returns the updated user details (see account/verify_credentials) On error: + * 403 FORBIDDEN: if not authenticated * 400 BADREQUEST: "no media data submitted", "profile_id not available" * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server", @@ -535,23 +678,33 @@ On error: "unable to process image data", "image upload failed" +--- -## Implemented API calls (not compatible with other APIs) +### friendships/incoming (*; AUTH) +#### Unsupported parameters + +* cursor +* stringify_ids + +## Implemented API calls (not compatible with other APIs) --- -### friendica/activity/ + +### 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 +* 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". @@ -560,39 +713,48 @@ Attend verbs should be used only with event-related items (there is no check at #### Return values On success: -json +json: + ```"ok"``` -xml +xml: + ```true``` On error: HTTP 400 BadRequest --- + ### friendica/group_show (*; AUTH) + Return all or a specified group of the user with the containing contacts as array. #### Parameters + * gid: optional, if not given, API returns all groups of the user #### Return values + Array of: * name: name of the group * gid: id of the group * user: array of group members (return from api_get_user() function for each member) - --- + ### friendica/group_delete (POST,DELETE; AUTH) + 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 #### Return values + Array of: * success: true if successfully deleted @@ -601,15 +763,18 @@ Array of: * status: „deleted“ if successfully deleted * wrong users: empty array - --- + ### friendica/group_create (POST,PUT; AUTH) + Create the group with the posted array of contacts as members. #### Parameters + * name: name of the group to be created #### POST data + JSON data as Array like the result of "users/group_show": * gid @@ -617,6 +782,7 @@ JSON data as Array like the result of "users/group_show": * array of users #### Return values + Array of: * success: true if successfully created or reactivated @@ -625,16 +791,19 @@ Array of: * status: „missing user“ | „reactivated“ | „ok“ * wrong users: array of users, which were not available in the contact table - --- + ### friendica/group_update (POST) + 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 #### POST data + JSON data as array like the result of „users/group_show“: * gid @@ -642,6 +811,7 @@ JSON data as array like the result of „users/group_show“: * array of users #### Return values + Array of: * success: true if successfully updated @@ -650,16 +820,18 @@ Array of: * status: „missing user“ | „ok“ * wrong users: array of users, which were not available in the contact table - - --- + ### friendica/notifications (GET) + Return last 50 notification for current user, ordered by date with unseen item on top #### Parameters + none #### Return values + Array of: * id: id of the note @@ -676,25 +848,30 @@ Array of: * link: link to note * seen: seen state: 0 or 1 - --- + ### friendica/notifications/seen (POST) + Set note as seen, returns item object if possible #### Parameters + id: id of the note to set seen #### Return values + If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api. If the note is not linked to an item, a success status is returned: -* "success" (json) | success;" (xml) - +* `success` (json) | `success` (xml) --- + ### friendica/photo (*; AUTH) + #### Parameters + * photo_id: Resource id of a photo. * scale: (optional) scale value of the photo @@ -716,8 +893,9 @@ An image used as profile image has only scale 4-6, other images only 0-3 #### Return values -json -``` +json: + +```json { "id": "photo id" "created": "date(YYYY-MM-DD HH:MM:SS)", @@ -740,8 +918,9 @@ json } ``` -xml -``` +xml: + +```xml photo id date(YYYY-MM-DD HH:MM:SS) @@ -762,14 +941,16 @@ xml ``` --- + ### friendica/photos/list (*; AUTH) Returns a list of all photo resources of the logged in user. #### Return values -json -``` +json: + +```json [ { id: "resource_id", @@ -782,8 +963,9 @@ json ] ``` -xml -``` +xml: + +```xml ensure that client is asking user for being sure to do this @@ -805,17 +990,21 @@ deletes all images with the specified album name, is not reversible -> ensure th #### Return values On success: + * JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."} On error: + * 403 FORBIDDEN: if not authenticated * 400 BADREQUEST: "no albumname specified", "album not available" * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed" - --- + ### friendica/photoalbum/update (POST,PUT; AUTH) + #### Parameters + * album: name of the album to be updated * album_new: new name of the album @@ -824,18 +1013,23 @@ changes the album name to album_new for all photos in album #### Return values On success: + * JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."} On error: + * 403 FORBIDDEN: if not authenticated * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available" * 500 INTERNALSERVERERROR: "unknown error - updating in database failed" - --- + ### friendica/photo/create (POST; AUTH) + ### friendica/photo/update (POST; AUTH) + #### Parameters + * photo_id (optional): if specified the photo with this id will be updated * media (optional): image data as base64, only optional if photo_id is specified (new upload must have media) * desc (optional): description for the photo, updated when photo_id is specified @@ -853,12 +1047,14 @@ Currently it is best to inform user that updating rights is not the right way to #### Return values On success: + * new photo uploaded: JSON return with photo data (see friendica/photo) * photo updated - changed photo data: JSON return with photo data (see friendica/photo) * photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."} * photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."} On error: + * 403 FORBIDDEN: if not authenticated * 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid" * 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server", @@ -869,10 +1065,12 @@ On error: "unknown error - update photo entry in database failed", "unknown error - this error on uploading or updating a photo should never happen" - --- + ### friendica/photo/delete (DELETE; AUTH) + #### Parameters + * photo_id: id of the photo to be deleted deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this @@ -881,50 +1079,66 @@ Sets item table entries for this photo to deleted = 1 #### Return values On success: + * JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."} On error: + * 403 FORBIDDEN: if not authenticated * 400 BADREQUEST: "no photo_id specified", "photo not available" * 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred" - --- + ### friendica/direct_messages_setseen (GET; AUTH) + #### Parameters + * id: id of the message to be updated as seen #### Return values On success: + * JSON return {"result":"ok","message":"message set to seen"} On error: + * different JSON returns {"result":"error","message":"xyz"} --- + ### friendica/direct_messages_search (GET; AUTH) + #### Parameters + * searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored) #### Return values + Returns only tested with JSON, XML might work as well. On success: + * JSON return {"success":"true","search_results": array of found messages} * JSOn return {"success":"false","search_results":"nothing found"} On error: + * different JSON returns {"result":"error","message":"searchstring not specified"} --- + ### friendica/profile/show (GET; AUTH) + show data of all profiles or a single profile of the authenticated user #### Parameters + * profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default) #### Return values + On success: Array of: * multi_profiles: true if user has activated multi_profiles @@ -937,6 +1151,7 @@ HTTP 403 Forbidden: when no authentication was provided HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user General description of profile data in API returns: + * profile_id * profile_name * is_default: true if this is the public profile @@ -949,14 +1164,9 @@ General description of profile data in API returns: * users: array with the users allowed to view this profile (empty if is_default=true) --- -### friendships/incoming (*; AUTH) - -#### Unsupported parameters -* cursor -* stringify_ids ---- ## Not Implemented API calls + The following API calls are implemented in GNU Social but not in Friendica: (incomplete) * statuses/retweets_of_me @@ -1041,12 +1251,16 @@ The following API calls from the Twitter API are not implemented in either Frien --- ## Usage Examples + ### BASH / cURL +```bash /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 [RSStoFriendika](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): -- 2.39.5