X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=doc%2Fapi.md;h=f3fae820143ae2c81831e6b0f86fffc0ed756097;hb=e2896b449b544e451d9a55f398b5990072cee644;hp=76b3f3dc809d0e357c4b18bc76c67e21ef812ec7;hpb=b3235c2d024f9eb150398011e1a3c503fba5ee54;p=friendica.git
diff --git a/doc/api.md b/doc/api.md
index 76b3f3dc80..f3fae82014 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -1,53 +1,28 @@
-# Friendica API
+# Using the APIs
* [Home](help)
-The Friendica API aims to be compatible with the [GNU Social API](http://wiki.gnusocial.de/gnusocial:api) and the [Twitter API](https://dev.twitter.com/rest/public).
+Friendica offers multiple API endpoints to interface with third-party applications:
-Please refer to the linked documentation for further information.
+- [Twitter](help/API-Twitter)
+- [Mastodon](help/API-Mastodon)
+- [Friendica-specific](help/API-Friendica)
+- [GNU Social](help/API-GNU-Social)
-## Implemented API calls
+## Usage
-### General
+### HTTP Method
-#### HTTP Method
-
-API endpoints can restrict the method used to request them.
+API endpoints can restrict the HTTP method used to request them.
Using an invalid method results in HTTP error 405 "Method Not Allowed".
-In this document, the required method is listed after the endpoint name. "*" means every method can be used.
-
-#### Auth
-
-Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.
-
-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
-* place_id: Not implemented in GNU Social
-* display_coordinates: Not implemented in GNU Social
-* include_rts: To-Do
-* include_my_retweet: Retweets in Friendica are implemented in a different way
-
-#### Different behaviour
+### Authentication
-* 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.
+Friendica supports basic HTTP Auth and OAuth to authenticate the user to the APIs.
-#### Return values
-
-* cid: Contact id of the user (important for "contact_allow" and "contact_deny")
-* network: network of the user
-
-#### Errors
+### Errors
When an error occurs in API call, an HTTP error code is returned, with an error message
Usually:
@@ -63,1292 +38,23 @@ Error body is
json:
```json
- {
- "error": "Specific error message",
- "request": "API path requested",
- "code": "HTTP error code"
- }
-```
-
-xml:
-
-```xml
-
- Specific error message
- API path requested
- HTTP error code
-
-```
-
----
-
-### 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
-* since_id: minimum id
-* max_id: maximum id
-* 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
-* max_id: maximum id
-* getText: Defines the format of the status field. Can be "html" or "plain"
-* include_entities: "true" shows entities for pictures and links (Default: false)
-* 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
-* max_id: maximum id
-* getText: Defines the format of the status field. Can be "html" or "plain"
-* 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
-* max_id: maximum id
-* getText: Defines the format of the status field. Can be "html" or "plain"
-* uri: URI of the 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
-* max_id: maximum id
-* getText: Defines the format of the status field. Can be "html" or "plain"
-* include_entities: "true" shows entities for pictures and links (Default: false)
-* 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
-* replyto: ID of the replied direct message
-* 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
-* friendica_verbose: "true" enables different error returns (default: "false")
-
-#### 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
-* max_id: maximum id
-* include_entities: "true" shows entities for pictures and links (Default: false)
-
-#### Unsupported parameters
-
-* user_id
-* screen_name
-
-Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.
-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
-
-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
-
-Friendica doesn't allow showing the friends of other users.
-
----
-
-### help/test (*)
-
----
-
-### lists/ownerships (*; AUTH)
-
-#### Parameters
-
-* list_id: ID of the list
-* count: Items per page
-* page: Page number
-* since_id: Minimum ID
-* max_id: Maximum ID
-
-#### Unsupported parameters
-
-* slug
-* owner_screen_name
-* owner_id
-* include_entities
-* include_rts
-
----
-
-### lists/destroy (POST; AUTH)
-
-#### Parameters
-
-* list_id: ID of the list
-
-#### Unsupported parameters
-
-* owner_screen_name
-* owner_id
-* slug
-
----
-
-### lists/create (POST; AUTH)
-
-#### Parameters
-
-* name: name of the list
-
-#### Unsupported parameters
-
-* mode
-* description
-
----
-
-### lists/update (POST; AUTH)
-
-#### Parameters
-
-* list_id: ID of the list
-* name: name of the list
-
-#### Unsupported parameters
-
-* slug
-* name
-* mode
-* description
-* owner_screen_name
-* owner_id
-
----
-
-### lists/statuses (*; AUTH)
-
-#### Parameters
-
-* user_id: ID of the user for whom to return results.
-
-#### Unsupported parameters
-
-* screen_name
-* count
-* cursor
-
----
-
-### 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
-
-* include_entities: "true" shows entities for pictures and links (Default: false)
-
----
-
-### statuses/friends (*; AUTH)
-
-#### Parameters
-
-* include_entities: "true" shows entities for pictures and links (Default: false)
-
----
-
-### blocks/list (*; AUTH)
-
-#### Parameters
-
-* include_entities: "true" shows entities for pictures and links (Default: false)
-* count: Items per page (default: 20).
-* 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
-* max_id: maximum id
-* exclude_replies: don't show replies (default: false)
-* conversation_id: Shows all statuses of a given conversation.
-* 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
-* max_id: maximum id
-* exclude_replies: don't show replies (default: false)
-* conversation_id: Shows all statuses of a given conversation.
-* 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
-* max_id: maximum id
-* 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
-* max_id: maximum id
-* exclude_replies: don't show replies (default: false)
-* conversation_id: Shows all statuses of a given conversation.
-* 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
-* max_id: maximum id
-* 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
-* max_id: maximum id
-* 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
-* in_reply_to_status_id
-* lat: latitude
-* long: longitude
-* media: image data
-* source: Application name
-* group_allow
-* contact_allow
-* group_deny
-* contact_deny
-* network
-* include_entities: "true" shows entities for pictures and links (Default: false)
-* 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)
-* page: page number
-* since_id: minimum id
-* max_id: maximum id
-* exclude_replies: don't show replies (default: false)
-* conversation_id: Shows all statuses of a given conversation.
-* include_entities: "true" shows entities for pictures and links (Default: false)
-
-#### Unsupported parameters
-
-* include_rts
-* trim_user
-* 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
-* since_id: minimum id
-* max_id: maximum id
-* include_entities: "true" shows entities for pictures and links (Default: false)
-
----
-
-### statusnet/version (*)
-
-#### Unsupported parameters
-
-* user_id
-* screen_name
-* cursor
-
-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
-* count: alias for the rpp parameter
-* since_id: returns statuses with ids greater than the given id
-* max_id: returns statuses with ids lower or equal to the given id
-
-#### Unsupported parameters
-
-* geocode
-* lang
-* locale
-* result_type
-* until
-* include_entities
-
----
-
-### search/tweets (*; AUTH)
-
-This is an alias for `search`.
-
----
-
-### saved_searches/list (*; AUTH)
-
-This call does not have any parameter.
-
----
-
-### 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
-
-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
-
-uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo
-
-#### 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",
- "image size exceeds Friendica Config setting (uploaded size: x)",
- "unable to process image data",
- "image upload failed"
-
----
-
-### account/update_profile (POST; AUTH)
-
-#### Parameters
-
-* name (optional): full name of the user
-* description (optional): a description of the user
-
-#### Unsupported parameters
-
-* url
-* location
-* profile_link_color
-* include_entities
-* skip_status
-
----
-
-### friendships/incoming (*; AUTH)
-
-#### Unsupported parameters
-
-* cursor
-* stringify_ids
-
-## Implemented API calls (not compatible with other APIs)
-
----
-
-### 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:
-
-```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
-* gid: gid of the deleted group
-* name: name of the deleted group
-* 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
-* name
-* array of users
-
-#### Return values
-
-Array of:
-
-* success: true if successfully created or reactivated
-* 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
-
----
-
-### 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
-* name
-* array of users
-
-#### Return values
-
-Array of:
-
-* success: true if successfully updated
-* 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
-
----
-
-### 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
-* type: type of notification as int (see NOTIFY_* constants in boot.php)
-* name: full name of the contact subject of the note
-* url: contact's profile url
-* photo: contact's profile photo
-* date: datetime string of the note
-* timestamp: timestamp of the node
-* date_rel: relative date of the note (eg. "1 hour ago")
-* msg: note message in bbcode
-* msg_html: note message in html
-* msg_plain: note message in plain text
-* 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)
-
----
-
-### friendica/photo (*; AUTH)
-
-#### 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:
-
-```json
- {
- "id": "photo id"
- "created": "date(YYYY-MM-DD HH:MM:SS)",
- "edited": "date(YYYY-MM-DD 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:
-
-```xml
-
- photo id
- date(YYYY-MM-DD HH:MM:SS)
- date(YYYY-MM-DD HH:MM:SS)
- photo title
- photo description
- album name
- original file name
- mime type
- number
- number
- 1 if is profile photo
-
-
- ...
-
-
-```
-
----
-
-### friendica/photos/list (*; AUTH)
-
-Returns a list of all photo resources of the logged in user.
-
-#### Return values
-
-json:
-
-```json
- [
- {
- id: "resource_id",
- album: "album name",
- filename: "original file name",
- type: "image mime type",
- thumb: "url to thumb sized image"
- },
- ...
- ]
+{
+ "error": "Specific error message",
+ "request": "API path requested",
+ "code": "HTTP error code"
+}
```
xml:
```xml
-
-
- "url to thumb sized image"
-
- ...
-
+
+ Specific error message
+ API path requested
+ HTTP error code
+
```
----
-
-### friendica/photoalbum/delete (POST,DELETE; AUTH)
-
-#### Parameters
-
-* album: name of the album to be deleted
-
-deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
-
-#### 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
-
-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
-* album: name of the album to be deleted (always necessary)
-* album_new (optional): can be used to change the album of a single photo if photo_id is specified
-* allow_cid/allow_gid/deny_cid/deny_gid (optional): on create: empty string or omitting = public photo, specify in format '``````' for private photo;
- on update: keys need to be present with empty values for changing a private photo to public
-
-both calls point to one function for creating AND updating photos.
-Saves data for the scales 0-2 to database (see above for scale description).
-Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo.
-Client should pay attention to the fact that updated access rights are not transferred to the contacts. i.e. public photos remain publicly visible if they have been commented/liked before setting visibility back to a limited group.
-Currently it is best to inform user that updating rights is not the right way to do this, and offer a solution to add photo as a new photo with the new rights instead.
-
-#### 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",
- "image size exceeds Friendica Config setting (uploaded size: x)",
- "unable to process image data",
- "image upload failed",
- "unknown error - uploading photo failed, see Friendica log for more information",
- "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
-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
-* global_dir: URL of the global directory set in server settings
-* friendica_owner: user data of the authenticated user
-* profiles: array of the profile data
-
-On error:
-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
-* hide_friends: true if friends are hidden
-* profile_photo
-* profile_thumb
-* publish: true if published on the server's local directory
-* net_publish: true if published to global_dir
-* description ... homepage: different data fields from 'profile' table in database
-* users: array with the users allowed to view this profile (empty if is_default=true)
-
----
-
-## Not Implemented API calls
-
-The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
-
-* statuses/retweets_of_me
-* friendships/create
-* friendships/destroy
-* friendships/exists
-* friendships/show
-* account/update_profile_background_image
-* blocks/create
-* blocks/destroy
-
-The following API calls from the Twitter API are not implemented in either Friendica or GNU Social:
-
-* statuses/mentions_timeline
-* statuses/retweets/:id
-* statuses/oembed
-* statuses/retweeters/ids
-* statuses/lookup
-* direct_messages/show
-* friendships/no_retweets/ids
-* friendships/outgoing
-* friendships/update
-* friends/list
-* friendships/lookup
-* account/settings
-* account/update_delivery_device
-* blocks/ids
-* users/show
-* users/search
-* account/remove_profile_banner
-* account/update_profile_banner
-* users/profile_banner
-* mutes/users/create
-* mutes/users/destroy
-* mutes/users/ids
-* mutes/users/list
-* users/suggestions/:slug
-* users/suggestions
-* users/suggestions/:slug/members
-* favorites/list
-* lists/list
-* lists/members/destroy
-* lists/memberships
-* lists/subscribers
-* lists/subscribers/create
-* lists/subscribers/show
-* lists/subscribers/destroy
-* lists/members/create_all
-* lists/members/show
-* lists/members
-* lists/members/create
-* lists/show
-* lists/subscriptions
-* lists/members/destroy_all
-* saved_searches/show/:id
-* saved_searches/create
-* saved_searches/destroy/:id
-* geo/id/:place_id
-* geo/reverse_geocode
-* geo/search
-* geo/place
-* trends/place
-* trends/available
-* help/configuration
-* help/languages
-* help/privacy
-* help/tos
-* trends/closest
-* users/report_spam
-
----
-
----
-
## Usage Examples
### BASH / cURL