Merge pull request #12839 from HankG/api-documentation-updates

API documentation updates

doc/API-Entities.md

@@ -908,6 +908,13 @@ Identical to [the Twitter Media Object](https://developer.twitter.com/en/docs/tw
 <td>Resource ID (32 hex chars)</td>
 </tr>
 
+<tr>
+<td><code>media-id</code></td>
+<td>String (Integer) </td>
+<td>ID used for attaching images to a Mastodon Post Status</td>
+</tr>
+
+
 <tr>
 <td><code>created</code></td>
 <td>String (Date)</td>
@@ -1001,6 +1008,14 @@ Mutually exclusive with <code>data</code> <code>datasize</code>.
 </td>
 </tr>
 
+<tr>
+<td><code>scales</code></td>
+<td>Array of Photo Scales</td>
+<td>
+List of the various resized versions of the Photo
+</td>
+</tr>
+
 <tr>
 <td><code>datasize</code></td>
 <td>Integer</td>
@@ -1040,6 +1055,58 @@ Mutually exclusive with <code>link</code>.
 </tbody>
 </table>
 
+## Photo Scale
+
+<table class="table table-condensed table-striped table-bordered">
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Type</th>
+<th align="center">Nullable</th>
+</tr>
+</thead>
+<tbody>
+
+<tr>
+<td><code>id</code></td>
+<td>String (Integer)</td>
+<td>Row ID of this photo scale</td>
+</tr>
+
+<tr>
+<td><code>scale</code></td>
+<td>Integer</td>
+<td>Scale number</td>
+</tr>
+
+<tr>
+<td><code>link</code></td>
+<td>String (URL)</td>
+<td>URL to this scale's image</td>
+</tr>
+
+<tr>
+<td><code>height</code></td>
+<td>Integer</td>
+<td>Image height in pixels</td>
+</tr>
+
+<tr>
+<td><code>width</code></td>
+<td>Integer</td>
+<td>Image width in pixels</td>
+</tr>
+
+<tr>
+<td><code>size</code></td>
+<td>Integer</td>
+<td>Image size in bytes</td>
+</tr>
+
+</tbody>
+</table>
+
+
 ## Photo List Item
 
 <table class="table table-condensed table-striped table-bordered">
@@ -1103,6 +1170,40 @@ Mutually exclusive with <code>link</code>.
 </tbody>
 </table>
 
+
+## Photo Album
+
+<table class="table table-condensed table-striped table-bordered">
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+
+<tr>
+<td><code>name</code></td>
+<td>String</td>
+<td>The name of the photo album</td>
+</tr>
+
+<tr>
+<td><code>created</code></td>
+<td>String (Date)</td>
+<td>The creation date of the album. Format <code>YYYY-MM-DD HH:MM:SS</code></td>
+</tr>
+
+<tr>
+<td><code>count</code></td>
+<td>Integer</td>
+<td>The number of images in the album</td>
+</tr>
+
+</tbody>
+</table>
+
 ## Private message
 
 <table class="table table-condensed table-striped table-bordered">

doc/API-Friendica.md

@@ -676,8 +676,92 @@ 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 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
+  }
+]
+```
+
+### GET api/friendica/photoalbum
+
+Get a list of images in a photo album
+#### Parameters
+
+* `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://<server>/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://<server>/photo/899184972463eb9b2ae3dc2580502826-0.png",
+        "width": 693,
+        "height": 835,
+        "size": 119523
+      },
+      ...
+    ],
+    "thumb": "https://<server>/photo/899184972463eb9b2ae3dc2580502826-2.png"
+  },
+  ...
+]
+```
+
 ---
 
+
 ### GET api/friendica/profile/show
 
 Returns the [Profile](help/API-Entities#Profile) data of the authenticated user.
@@ -715,6 +799,127 @@ General description of profile data in API returns:
 
 ---
 
+### POST api/friendica/statuses/:id/dislike
+
+Marks the given status as disliked by 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://<server_name>/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://<server_name>/api/friendica/statuses/341/disliked_by`
+
+```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://<server_name>/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
 
 - POST api/statuses/mediap

doc/API-Mastodon.md

@@ -30,6 +30,91 @@ For supported apps please have a look at the [FAQ](help/FAQ#clients)
 ## Entities
 
 These endpoints use the [Mastodon API entities](https://docs.joinmastodon.org/entities/).
+With some additional extensions listed below.
+
+### Instance (Version 2) Entities
+Extensions to the [Mastodon Instance::V2 Entities](https://docs.joinmastodon.org/entities/Instance/)
+* `friendica`: Friendica specific properties of the V2 Instance including:
+    * `version`: The Friendica version string
+    * `codename`: The Friendica version code name
+    * `db_version`: The database schema version number
+
+Example: 
+```json
+{
+  "domain": "friendicadevtest1.myportal.social",
+  "title": "Friendica Social Network",
+  "version": "2.8.0 (compatible; Friendica 2023.03-dev)",
+  ...
+  "friendica": {
+    "version": "2023.03-dev",
+    "codename": "Giant Rhubarb",
+    "db_version": 1516
+  }
+}
+```
+
+### Notification Entities
+Extensions to the [Mastodon Notification Entities](https://docs.joinmastodon.org/entities/Notification/)
+* `dismissed`: whether the object has been dismissed or not
+
+### Status Entities
+Extensions to the [Mastodon Status Entities](https://docs.joinmastodon.org/entities/Status/)
+* `in_reply_to_status`: A fully populated Mastodon Status entity for the replied to status or null it is a post rather than a response
+* `friendica`: Friendica specific properties of a status including:
+  * `title`: The Friendica title for a post, or empty if the status is a comment
+  * `dislikes_count`: The number of dislikes that a status has accumulated according to the server.
+
+Example:
+```json
+{
+  "id": "358",
+  "created_at": "2023-02-23T02:45:46.000Z",
+  "in_reply_to_id": "356",
+  "in_reply_to_status": {
+    "id": "356",
+    "created_at": "2023-02-23T02:45:35.000Z",
+    "in_reply_to_id": null,
+    "in_reply_to_status": null,
+    "in_reply_to_account_id": null,
+    ...
+    "content": "A post from testuser1",
+    ...
+    "account": {
+      "id": "6",
+      "username": "testuser1",
+      "acct": "testuser1",
+      "display_name": "testuser1",
+      ...
+    },
+    ...
+    "friendica": {
+      "title": "",
+      "dislikes_count": 0
+    }
+  },
+  "in_reply_to_account_id": "6",
+  ...
+  "replies_count": 0,
+  "reblogs_count": 0,
+  "favourites_count": 0,
+  ...
+  "content": "A reply from testuser2",
+  ...
+  "account": {
+    "id": "8",
+    "username": "testuser2",
+    "acct": "testuser2",
+    "display_name": "testuser2",
+    ...
+  },
+  ...
+  "friendica": {
+    "title": "",
+    "dislikes_count": 0
+  }
+}
+```
 
 ## Implemented endpoints
 
@@ -73,8 +158,8 @@ These endpoints use the [Mastodon API entities](https://docs.joinmastodon.org/en
     - `:id` is a follow request ID, not a regular account id
     - Returns a [Relationship](https://docs.joinmastodon.org/entities/relationship) object.
 
-- [`GET /api/v1/followed_tags'](https://docs.joinmastodon.org/methods/followed_tags/)
+- [`GET /api/v1/followed_tags`](https://docs.joinmastodon.org/methods/followed_tags/)
-- [`GET /api/v1/instance`](https://docs.joinmastodon.org/methods/instance#fetch-instance)
+- [`GET /api/v1/instance`](https://docs.joinmastodon.org/methods/instance/#v1)
 - `GET /api/v1/instance/rules` Undocumented, returns Terms of Service
 - [`GET /api/v1/instance/peers`](https://docs.joinmastodon.org/methods/instance#list-of-connected-domains)
 - [`GET /api/v1/lists`](https://docs.joinmastodon.org/methods/timelines/lists/)
@@ -92,6 +177,10 @@ These endpoints use the [Mastodon API entities](https://docs.joinmastodon.org/en
 - [`PUT /api/v1/media/:id`](https://docs.joinmastodon.org/methods/statuses/media/)
 - [`GET /api/v1/mutes`](https://docs.joinmastodon.org/methods/accounts/mutes/)
 - [`GET /api/v1/notifications`](https://docs.joinmastodon.org/methods/notifications/)
+    - Additional field `include_all` to return read and unread statuses, defaults to `false`
+    - Additional field `summary` returns a count of all of the statuses that match the type filter
+    - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
+    - Does not support the `type` field, which is the mirror image of the supported `exclude_types` field
 - [`GET /api/v1/notifications/:id`](https://docs.joinmastodon.org/methods/notifications/)
 - [`POST /api/v1/notifications/clear`](https://docs.joinmastodon.org/methods/notifications/)
 - [`POST /api/v1/notifications/:id/dismiss`](https://docs.joinmastodon.org/methods/notifications/)
@@ -106,11 +195,22 @@ These endpoints use the [Mastodon API entities](https://docs.joinmastodon.org/en
 - [`DELETE /api/v1/scheduled_statuses/:id`](https://docs.joinmastodon.org/methods/statuses/scheduled_statuses/)
 - [`GET /api/v1/scheduled_statuses/:id`](https://docs.joinmastodon.org/methods/statuses/scheduled_statuses/)
 - [`GET /api/v1/search`](https://docs.joinmastodon.org/methods/search/)
+- [`PUT /api/v1/statuses`](https://docs.joinmastodon.org/methods/statuses/#edit)
+    - Does not support `polls` argument as Friendica does not have polls
+    - Additional fields `friendica` for Friendica specific parameters:
+        - `title`: Explicitly sets the title for a post status, ignored if used on a comment status. For post statuses the legacy behavior is to use any "spoiler text" as the title if it is provided. If both the title and spoiler text are provided for a post status then they will each be used for their respective roles. If no title is provided then the legacy behavior will persist. If you want to create a post with no title but spoiler text then explicitly set the title but set it to an empty string `""`.
 - [`POST /api/v1/statuses`](https://docs.joinmastodon.org/methods/statuses/#create)
+    - Does not support `polls` argument as Friendica does not have polls
     - Additionally to the static values `public`, `unlisted` and `private`, the `visibility` parameter can contain a numeric value with a group id.
+    - Additional field `quote_id` for the post that is being quote reshared
+    - Additional fields `friendica` for Friendica specific parameters:
+       - `title`: Explicitly sets the title for a post status, ignored if used on a comment status. For post statuses the legacy behavior is to use any "spoiler text" as the title if it is provided. If both the title and spoiler text are provided for a post status then they will each be used for their respective roles. If no title is provided then the legacy behavior will persist. If you want to create a post with no title but spoiler text then explicitly set the title but set it to an empty string `""`. 
 - [`GET /api/v1/statuses/:id`](https://docs.joinmastodon.org/methods/statuses/#get)
 - [`DELETE /api/v1/statuses/:id`](https://docs.joinmastodon.org/methods/statuses/#delete)
 - [`GET /api/v1/statuses/:id/context`](https://docs.joinmastodon.org/methods/statuses/#context)
+    - Additional support for paging using `min_id`, `max_id`, `since_id` parameters
+    - Additional support for previous/next Link Headers to support paging
+    - Additional flag `show_all` to allow including posts from blocked and ignored/muted users, defaults to `false`
 - [`GET /api/v1/statuses/:id/reblogged_by`](https://docs.joinmastodon.org/methods/statuses/#reblogged_by)
 - [`GET /api/v1/statuses/:id/favourited_by`](https://docs.joinmastodon.org/methods/statuses/#favourited_by)
 - [`POST /api/v1/statuses/:id/favourite`](https://docs.joinmastodon.org/methods/statuses/#favourite)
@@ -132,13 +232,24 @@ These endpoints use the [Mastodon API entities](https://docs.joinmastodon.org/en
 - [`GET /api/v1/tags/:id/unfollow`](https://docs.joinmastodon.org/methods/tags/#unfollow)
 - [`GET /api/v1/timelines/direct`](https://docs.joinmastodon.org/methods/timelines/)
 - [`GET /api/v1/timelines/home`](https://docs.joinmastodon.org/methods/timelines/)
+    - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
+    - Additional field `exclude_replies` to only return post statuses not replies/comments, defaults to `false`
 - [`GET /api/v1/timelines/list/:id`](https://docs.joinmastodon.org/methods/timelines/)
+    - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
+    - Additional field `exclude_replies` to only return post statuses not replies/comments, defaults to `false`
 - [`GET /api/v1/timelines/public`](https://docs.joinmastodon.org/methods/timelines/)
+    - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
+    - Additional field `exclude_replies` to only return post statuses not replies/comments, defaults to `false`
 - [`GET /api/v1/timelines/tag/:hashtag`](https://docs.joinmastodon.org/methods/timelines/)
+    - Additional field `with_muted` Pleroma extension to return notifications from muted users, defaults to `false`
+    - Additional field `exclude_replies` to only return post statuses not replies/comments, defaults to `false`
+    - Does not support the `any[]`, `all[]`, or `none[]` query parameters
 - [`GET /api/v1/trends`](https://docs.joinmastodon.org/methods/instance/trends/)
 - [`GET /api/v1/trends/links`](https://github.com/mastodon/mastodon/pull/16917)
 - [`GET /api/v1/trends/statuses`](https://docs.joinmastodon.org/methods/trends/#statuses)
 - [`GET /api/v1/trends/tags`](https://docs.joinmastodon.org/methods/trends/#tags)
+    - Additional field `friendica_local` to return local trending tags instead of global tags, defaults to `false`
+- [`GET /api/v2/instance`](https://docs.joinmastodon.org/methods/instance/#v2)
 - [`GET /api/v2/search`](https://docs.joinmastodon.org/methods/search/)