From 2d430679468a4c6a9b5c365a53f007cfa28679d9 Mon Sep 17 00:00:00 2001 From: tusooa Date: Sat, 1 Apr 2023 02:24:30 -0400 Subject: Document the streaming endpoint --- .../API/differences_in_mastoapi_responses.md | 116 +++++++++++++++++++++ 1 file changed, 116 insertions(+) (limited to 'docs/development/API/differences_in_mastoapi_responses.md') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 4007c63c8..ef6b3b3be 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -357,6 +357,122 @@ The message payload consist of: - `follower_count`: follower count - `following_count`: following count +### Authenticating via `sec-websocket-protocol` header + +Pleroma allows to authenticate via the `sec-websocket-protocol` header, for example, if your access token is `your-access-token`, you can authenticate using the following: + +``` +sec-websocket-protocol: your-access-token +``` + +### Authenticating after connection via `pleroma:authenticate` event + +Pleroma allows to authenticate after connection is established, via the `pleroma:authenticate` event. For example, if your access token is `your-access-token`, you can send the following after the connection is established: + +``` +{"type": "pleroma:authenticate", "token": "your-access-token"} +``` + +### Response to client-sent events + +Pleroma will respond to client-sent events that it recognizes. Supported event types are: + +- `subscribe` +- `unsubscribe` +- `pleroma:authenticate` + +The reply will be in the following format: + +``` +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"\", \"result\": \"\", \"error\": \"\"}" +} +``` + +Result of the action can be either `success`, `ignored` or `error`. If it is `error`, the `error` property will contain the error code. Otherwise, the `error` property will not be present. Below are some examples: + +``` +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"pleroma:authenticate\", \"result\": \"success\"}" +} + +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"subscribe\", \"result\": \"ignored\"}" +} + +{ + "event": "pleroma:respond", + "payload": "{\"type\": \"unsubscribe\", \"result\": \"error\", \"error\": \"bad_topic\"}" +} +``` + +If the sent event is not of a type that Pleroma supports, it will not reply. + +### The `stream` attribute of a server-sent event + +Technically, this is in Mastodon, but its documentation does nothing to specify its format. + +This attribute appears on every event type except `pleroma:respond` and `delete`. It helps clients determine where they should display the new statuses. + +The value of the attribute is an array containing one or two elements. The first element is the type of the stream. The second is the identifier related to that specific stream, if applicable. + +For the following stream types, there is a second element in the array: + +- `list`: The second element is the id of the list. +- `hashtag`: The second element is the name of the hashtag. +- `public:remote:media` and `public:remote`: The second element is the domain of the corresponding instance. + +For all other stream types, there is no second element. + +Some examples of valid `stream` values: + +- `list:1`: List of id 1. +- `hashtag:mew`: The hashtag #mew. +- `user:notifications`: Notifications for the current user. +- `user`: Home timeline. +- `public:remote:mew.moe`: Public posts from the instance mew.moe . + +### The unified streaming endpoint + +If you do not specify a stream to connect to when requesting `/api/v1/streaming`, you will enter a connection that subscribes to no streams. After the connection is established, you can authenticate and then subscribe to different streams. + +### List of supported streams + +Below is a list of supported streams by Pleroma. To make a single-stream WebSocket connection, append the string specified in "Query style" to the streaming endpoint url. +To subscribe to a stream after the connection is established, merge the JSON object specified in "Subscribe style" with `{"type": "subscribe"}`. To unsubscribe, merge it with `{"type": "unsubscribe"}`. + +For example, to receive updates on the list 1, you can connect to `/api/v1/streaming/?stream=list&list=1`, or send + +``` +{"type": "subscribe", "stream": "list", "list": 1} +``` + +upon establishing the websocket connection. + +To unsubscribe to list 1, send + +``` +{"type": "unsubscribe", "stream": "list", "list": 1} +``` + +Note that if you specify a stream that requires a logged-in user in the query string (for example, `user` or `list`), you have to specify the access token when you are trying to establish the connection, i.e. in the query string or via the `sec-websocket-protocol` header. + +- `list` + - Query style: `?stream=list&list=` + - Subscribe style: `{"stream": "list", "list": }` +- `public`, `public:local`, `public:media`, `public:local:media`, `user`, `user:pleroma_chat`, `user:notifications`, `direct` + - Query style: `?stream=` + - Subscribe style: `{"stream": ""}` +- `hashtag` + - Query style: `?stream=hashtag&tag=` + - Subscribe style: `{"stream": "hashtag", "tag": ""}` +- `public:remote`, `public:remote:media` + - Query style: `?stream=&instance=` + - Subscribe style: `{"stream": "", "instance": ""}` + ## User muting and thread muting Both user muting and thread muting can be done for only a certain time by adding an `expires_in` parameter to the API calls and giving the expiration time in seconds. -- cgit v1.2.3 From 7f12ad6dccfe4c81fa7e0d4e66c43bedadbf4c6a Mon Sep 17 00:00:00 2001 From: tusooa Date: Sat, 1 Apr 2023 02:37:19 -0400 Subject: Fix docs wording --- .../API/differences_in_mastoapi_responses.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/development/API/differences_in_mastoapi_responses.md') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index ef6b3b3be..48a9c104c 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -421,7 +421,7 @@ The value of the attribute is an array containing one or two elements. The first For the following stream types, there is a second element in the array: -- `list`: The second element is the id of the list. +- `list`: The second element is the id of the list, as a string. - `hashtag`: The second element is the name of the hashtag. - `public:remote:media` and `public:remote`: The second element is the domain of the corresponding instance. @@ -429,11 +429,11 @@ For all other stream types, there is no second element. Some examples of valid `stream` values: -- `list:1`: List of id 1. -- `hashtag:mew`: The hashtag #mew. -- `user:notifications`: Notifications for the current user. -- `user`: Home timeline. -- `public:remote:mew.moe`: Public posts from the instance mew.moe . +- `["list", "1"]`: List of id 1. +- `["hashtag", "mew"]`: The hashtag #mew. +- `["user:notifications"]`: Notifications for the current user. +- `["user"]`: Home timeline. +- `["public:remote", "mew.moe"]`: Public posts from the instance mew.moe . ### The unified streaming endpoint @@ -447,7 +447,7 @@ To subscribe to a stream after the connection is established, merge the JSON obj For example, to receive updates on the list 1, you can connect to `/api/v1/streaming/?stream=list&list=1`, or send ``` -{"type": "subscribe", "stream": "list", "list": 1} +{"type": "subscribe", "stream": "list", "list": "1"} ``` upon establishing the websocket connection. @@ -455,14 +455,14 @@ upon establishing the websocket connection. To unsubscribe to list 1, send ``` -{"type": "unsubscribe", "stream": "list", "list": 1} +{"type": "unsubscribe", "stream": "list", "list": "1"} ``` Note that if you specify a stream that requires a logged-in user in the query string (for example, `user` or `list`), you have to specify the access token when you are trying to establish the connection, i.e. in the query string or via the `sec-websocket-protocol` header. - `list` - Query style: `?stream=list&list=` - - Subscribe style: `{"stream": "list", "list": }` + - Subscribe style: `{"stream": "list", "list": ""}` - `public`, `public:local`, `public:media`, `public:local:media`, `user`, `user:pleroma_chat`, `user:notifications`, `direct` - Query style: `?stream=` - Subscribe style: `{"stream": ""}` -- cgit v1.2.3 From b39403a48fdb861b905bea16febba6d1660bb8df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Wed, 17 Jan 2024 17:12:40 +0100 Subject: Update API docs for my changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/development/API/differences_in_mastoapi_responses.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'docs/development/API/differences_in_mastoapi_responses.md') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 48a9c104c..2937b2301 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -1,6 +1,6 @@ # Differences in Mastodon API responses from vanilla Mastodon -A Pleroma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` +A Pleroma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` and `/api/v2/instance` ## Flake IDs @@ -39,6 +39,7 @@ Has these additional fields under the `pleroma` object: - `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint. - `parent_visible`: If the parent of this post is visible to the user or not. - `pinned_at`: a datetime (iso8601) when status was pinned, `null` otherwise. +- `quotes_count`: the count of status quotes. The `GET /api/v1/statuses/:id/source` endpoint additionally has the following attributes: @@ -304,19 +305,27 @@ Has these additional parameters (which are the same as in Pleroma-API): `GET /api/v1/instance` has additional fields - `max_toot_chars`: The maximum characters per post +- `max_media_attachments`: Maximum number of post media attachments - `chat_limit`: The maximum characters per chat message - `description_limit`: The maximum characters per image description - `poll_limits`: The limits of polls +- `shout_limit`: The maximum characters per Shoutbox message - `upload_limit`: The maximum upload file size - `avatar_upload_limit`: The same for avatars - `background_upload_limit`: The same for backgrounds - `banner_upload_limit`: The same for banners - `background_image`: A background image that frontends can use +- `pleroma.metadata.account_activation_required`: Whether users are required to confirm their emails before signing in +- `pleroma.metadata.birthday_required`: Whether users are required to provide their birth day when signing in +- `pleroma.metadata.birthday_min_age`: The minimum user age (in days) - `pleroma.metadata.features`: A list of supported features - `pleroma.metadata.federation`: The federation restrictions of this instance - `pleroma.metadata.fields_limits`: A list of values detailing the length and count limitation for various instance-configurable fields. - `pleroma.metadata.post_formats`: A list of the allowed post format types -- `vapid_public_key`: The public key needed for push messages +- `pleroma.stats.mau`: Monthly active user count +- `pleroma.vapid_public_key`: The public key needed for push messages + +In, `GET /api/v2/instance` Pleroma-specific fields are all moved into `pleroma` object. `max_toot_chars`, `poll_limits` and `upload_limit` are replaced with their MastoAPI counterparts. ## Push Subscription -- cgit v1.2.3 From fa02a1e634632bb672b53c244179d3088ffe8423 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Fri, 19 Jan 2024 18:05:46 +0100 Subject: Update MastoAPI responses docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/development/API/differences_in_mastoapi_responses.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/development/API/differences_in_mastoapi_responses.md') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 48a9c104c..70c31272d 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -39,6 +39,7 @@ Has these additional fields under the `pleroma` object: - `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint. - `parent_visible`: If the parent of this post is visible to the user or not. - `pinned_at`: a datetime (iso8601) when status was pinned, `null` otherwise. +- `non_anonymous`: true if the source post specifies the poll results are not anonymous. Currently only implemented by Smithereen. The `GET /api/v1/statuses/:id/source` endpoint additionally has the following attributes: -- cgit v1.2.3 From d415686bb9248e1c5b8913b7c3b96f74e9b8f230 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= Date: Mon, 26 Feb 2024 23:45:02 +0100 Subject: Allow to group bookmarks in folders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: marcin mikołajczak --- docs/development/API/differences_in_mastoapi_responses.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/development/API/differences_in_mastoapi_responses.md') diff --git a/docs/development/API/differences_in_mastoapi_responses.md b/docs/development/API/differences_in_mastoapi_responses.md index 2937b2301..d72717483 100644 --- a/docs/development/API/differences_in_mastoapi_responses.md +++ b/docs/development/API/differences_in_mastoapi_responses.md @@ -40,6 +40,7 @@ Has these additional fields under the `pleroma` object: - `parent_visible`: If the parent of this post is visible to the user or not. - `pinned_at`: a datetime (iso8601) when status was pinned, `null` otherwise. - `quotes_count`: the count of status quotes. +- `bookmark_folder`: the ID of the folder bookmark is stored within (if any). The `GET /api/v1/statuses/:id/source` endpoint additionally has the following attributes: @@ -65,6 +66,12 @@ Some apps operate under the assumption that no more than 4 attachments can be re Pleroma does not process remote images and therefore cannot include fields such as `meta` and `blurhash`. It does not support focal points or aspect ratios. The frontend is expected to handle it. +## Bookmarks + +The `GET /api/v1/bookmarks` endpoint accepts optional parameter `folder_id` for bookmark folder ID. + +The `POST /api/v1/statuses/:id/bookmark` endpoint accepts optional parameter `folder_id` for bookmark folder ID. + ## Accounts The `id` parameter can also be the `nickname` of the user. This only works in these endpoints, not the deeper nested ones for following etc. -- cgit v1.2.3