X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=doc%2FAPI-Friendica.md;h=a33cd53b86faba53252f2bfa1af63a26f66e5bb8;hb=927a8c00c0823d6cf607de28fa7b4dc2db584648;hp=84467430aea878385a086a05ed06ccd8df24a96d;hpb=09de4a5b47439542d5e73d5452e1d30da26c3ae6;p=friendica.git diff --git a/doc/API-Friendica.md b/doc/API-Friendica.md index 84467430ae..a33cd53b86 100644 --- a/doc/API-Friendica.md +++ b/doc/API-Friendica.md @@ -15,6 +15,41 @@ These endpoints uses the [Friendica API entities](help/API-Entities). ## Endpoints +### GET api/friendica/events + +Returns a list of [Event](help/API-Entities#Event) entities for the current logged in user. + +#### Parameters + +- `since_id`: (optional) minimum event id for pagination +- `count`: maximum number of items returned, default 20 + +### POST api/friendica/event_create + +Create a new event for the current logged in user. + +#### Parameters + +- `id` : (optional) id of event, event will be amended if supplied +- `name` : name of the event (required) +- `start_time` : start of the event (ISO), required +- `end_time` : (optional) end of the event, event is open end, if not supplied +- `desc` : (optional) description of the event +- `place` : (optional) location of the event +- `publish` : (optional) create message for event +- `allow_cid` : (optional) ACL-formatted list of allowed contact ids if private event +- `allow_gid` : (optional) ACL-formatted list of disallowed contact ids if private event +- `deny_cid` : (optional) ACL-formatted list of allowed group ids if private event +- `deny_gid` : (optional) ACL-formatted list of disallowed group ids if private event + +### POST api/friendica/event_delete + +Delete event from calendar (not the message) + +#### Parameters + +- `id` : id of event to be deleted + ### GET api/externalprofile/show Returns a [Contact](help/API-Entities#Contact) entity for the provided profile URL. @@ -211,7 +246,7 @@ Deprecated Twitter sent direct message list endpoint. Returns [Private Messages] * `friendica_verbose`: "true" enables different error returns (default: "false") -### POST/PUT api/direct_messages/new +### POST api/direct_messages/new Deprecated Twitter direct message submission endpoint. @@ -223,7 +258,7 @@ Deprecated Twitter direct message submission endpoint. * `replyto`: ID of the replied direct message * `title`: Title of the direct message -### POST/DELETE api/direct_messages/destroy +### POST api/direct_messages/destroy Deprecated Twitter direct message deletion endpoint. @@ -304,7 +339,7 @@ Array of: * `gid`: id of the group * `user`: array of [Contacts](help/API-Entities#Contact) -### POST/PUT api/friendica/group_create +### POST api/friendica/group_create Create the group with the posted array of contacts as members. @@ -357,7 +392,7 @@ Array of: * `status`: "missing user" | "ok" * `wrong users`: array of users, which were not available in the contact table -### POST/DELETE api/friendica/group_delete +### POST api/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. @@ -556,7 +591,7 @@ On error: "unknown error - update photo entry in database failed", "unknown error - this error on uploading or updating a photo should never happen" -### DELETE api/friendica/photo/delete +### POST api/friendica/photo/delete 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. @@ -586,7 +621,7 @@ On error: --- -### POST/DELETE api/friendica/photoalbum/delete +### POST api/friendica/photoalbum/delete Deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this. @@ -613,7 +648,7 @@ On error: * 400 BADREQUEST: "no albumname specified", "album not available" * 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed" -### POST/PUT api/friendica/photoalbum/update +### POST api/friendica/photoalbum/update Changes the album name to album_new for all photos in album. @@ -630,8 +665,8 @@ On success: ```json { - "result": "updated", - "message":"album 'abc' with all containing photos has been renamed to 'xyz'." + "result": "updated", + "message":"album 'abc' with all containing photos has been renamed to 'xyz'." } ``` @@ -641,15 +676,95 @@ On error: * 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available" * 500 INTERNALSERVERERROR: "unknown error - updating in database failed" ---- +### GET api/friendica/photoalbums -### GET api/friendica/profile/show +Get a list of photo albums for the user + +#### Parameters + +None +#### Return values + +On success a list of photo album objects: + +```json +[ + { + "name": "Wall Photos", + "created": "2023-01-22 02:03:19", + "count": 4 + }, + { + "name": "Profile photos", + "created": "2022-11-20 14:40:06", + "count": 1 + } +] +``` -Returns the [Profile](help/API-Entities#Profile) data of all profiles or a single profile of the authenticated user. +### GET api/friendica/photoalbum +Get a list of images in a photo album #### Parameters -* `profile_id` (optional): id of the profile to be returned. If omitted all profiles are returned by default. +* `album` (Required): name of the album to be deleted +* `limit` (Optional): Maximum number of items to get, defaults to 50, max 500 +* `offset`(Optional): Offset in results to page through total items, defaults to 0 +* `latest_first` (Optional): Reverse the order so the most recent images are first, defaults to false + +#### Return values + +On success: + +* JSON return with the list of Photo items + +**Example:** +`https:///api/friendica/photoalbum?album=Wall Photos&limit=10&offset=2` + +```json +[ + { + "created": "2023-02-14 14:31:06", + "edited": "2023-02-14 14:31:14", + "title": "", + "desc": "", + "album": "Wall Photos", + "filename": "image.png", + "type": "image/png", + "height": 835, + "width": 693, + "datasize": 119523, + "profile": 0, + "allow_cid": "", + "deny_cid": "", + "allow_gid": "", + "deny_gid": "", + "id": "899184972463eb9b2ae3dc2580502826", + "scale": 0, + "media-id": 52, + "scales": [ + { + "id": 52, + "scale": 0, + "link": "https:///photo/899184972463eb9b2ae3dc2580502826-0.png", + "width": 693, + "height": 835, + "size": 119523 + }, + ... + ], + "thumb": "https:///photo/899184972463eb9b2ae3dc2580502826-2.png" + }, + ... +] +``` + +--- + + +### GET api/friendica/profile/show + +Returns the [Profile](help/API-Entities#Profile) data of the authenticated user. #### Return values @@ -664,17 +779,146 @@ 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: +- 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 +- fullname +- date_of_birth +- description +- xmpp +- homepage +- address +- locality +- region +- postal_code +- country +- pub_keywords +- custom_fields: list of public custom fields --- -### GET api/friendica/remoteauth +### POST api/friendica/statuses/:id/dislike -Similar as /redir, redirects to `url` after DFRN authentication. +Marks the given status as disliked by this user -#### Parameters +#### Path Parameter + +* `id`: the status ID that is being marked + +#### Return values + +A Mastodon [Status Entity](https://docs.joinmastodon.org/entities/Status/) + +#### Example: +`https:///api/friendica/statuses/341/dislike` + +```json +{ + "id": "341", + "created_at": "2023-02-23T01:50:00.000Z", + "in_reply_to_id": null, + "in_reply_to_status": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + ... + "account": { + "id": "8", + "username": "testuser2", + ... + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null, + "friendica": { + "title": "", + "dislikes_count": 1 + } +} +``` + + +### GET api/friendica/statuses/:id/disliked_by + +Returns the list of accounts that have disliked the status as known by the current server + +#### Path Parameter + +* `id`: the status ID that is being marked + +#### Return values + +A list of [Mastodon Account](https://docs.joinmastodon.org/entities/Account/) objects +in the body and next/previous link headers in the header + +#### Example: +`https:///api/friendica/statuses/341/disliked_by` -- `c_url`: url of remote contact to auth to -- `url`: string, url to redirect after auth +```json +[ + { + "id": "6", + "username": "testuser1", + ... + } +] +``` + + + +### POST api/friendica/statuses/:id/undislike + +Removes the dislike mark (if it exists) on this status for this user + +#### Path Parameter + +* `id`: the status ID that is being marked + +#### Return values + +A Mastodon [Status Entity](https://docs.joinmastodon.org/entities/Status/) + +#### Example: +`https:///api/friendica/statuses/341/dislike` + +```json +{ + "id": "341", + "created_at": "2023-02-23T01:50:00.000Z", + "in_reply_to_id": null, + "in_reply_to_status": null, + "in_reply_to_account_id": null, + "sensitive": false, + "spoiler_text": "", + "visibility": "public", + "language": "en", + ... + "account": { + "id": "8", + "username": "testuser2", + ... + }, + "media_attachments": [], + "mentions": [], + "tags": [], + "emojis": [], + "card": null, + "poll": null, + "friendica": { + "title": "", + "dislikes_count": 0 + } +} +``` + +--- ## Deprecated endpoints