[Feature]: Implement Glitch extensions to Mastodon API for emoji reactions
Goal: make it easy for extended Mastodon clients to support emoji reactions, a fun Firefish feature.
Glitch PR #2221 proposes an extended Mastodon API for emoji reactions to Mastodon statuses (and an implementation, but that part's not relevant to us). This PR hasn't been merged to current Glitch yet, but it's already deployed in production on a handful of Glitch derivatives including Nyastodon (where it originated) and Catstodon. The API is likely stable but of course nobody can make any promises until it actually gets merged.
Ideally, both Firefish and Glitch ship this exact API, and then it's a de facto standard in case anyone else wants to implement it. I don't expect it to ever make it back to vanilla Mastodon. Akkoma has its own Mastodon-compatible client API for emoji reactions, but everything's namespaced into Pleroma-specific locations and it's not something I'd expect to see other projects use.
Acceptance criteria
A reactions-aware Mastodon-compatible client should be able to display, add, and remove emoji reactions from Firefish through the Mastodon compatibility API, in the same way as the client would do so any Mastodon instance running that Glitch patch. Few such clients exist, but I work on Feditext and have already implemented most of the client-side support for it.
Plan
I think I can implement this myself. Once it's working as a prototype, I'll let the Glitch people know that we're looking at shipping the API like this.
API details
Action items in bold. There's a lot of text here but I suspect the actual patch will be small, mostly in the Mastodon compatiblity API endpoints and converters, possibly also in Megalodon.
Entities
Status
entities in the Glitch patch have an additional reactions
property not present in vanilla Mastodon. This is a list of Reaction
entities, just like the reactions
property on Mastodon Announcement
entities. The Firefish Status
entity instead has an emoji_reactions
property, which should be renamed to reactions
to match.
Firefish Reaction
entities are almost the same as Mastodon Reaction
entities. There are three differences:
- The Firefish reaction
name
has leading and trailing:
on custom emoji, which should not be there. If these are removed, the name corresponds to theshortcode
for custom emoji used in other places in the Mastodon API. We should remove the colons.- For Unicode emoji, there are no colons, and no change is necessary.
- Firefish reactions have an optional list of associated
accounts
that responded with that reaction. (It wasn't populated in my testing, but that might have something to do with privacy settings.) This isn't part of the Glitch patch, so clients can use it if it's present and ignore it if not. No action needed here. - Firefish reactions are missing the
static_url
field. This is the same as theurl
field but returns a non-animated version of the resource. We should addstatic_url
.
Endpoints
All endpoints that return a Status
should also return its reactions. I think this is already true in Firefish. However, the reactions for custom emoji currently don't have their url
or static_url
fields populated. The Status
that the converter receives already has custom emoji used by reactions in its emojis
field, including url
and static_url
. Unlike custom emoji used in the post body, all custom emoji used by reactions have a suffix: this is @.
for local emoji and @domain.tld
for emoji from other servers.
I think we can populate the url
and static_url
fields in the entity converter with the following transform:
- Split the
emojis
list into non-reaction emoji with no@
in their name, and reaction emoji with an@
somewhere in their name. - The reaction emoji should be removed from the status's
emojis
list, since they're not used to render the post, leaving only non-reaction emoji. - Reactions should be looked up in the reaction emoji list by matching reaction
name
(with colons removed as above) to emojishortcode
. If there's a match, theurl
andstatic_url
fields should be copied from the emoji to the reaction.
Firefish should add two new Status
-related endpoints: POST /api/v1/statuses/:id/react/:name
and POST /api/v1/statuses/:id/unreact/:name
. These should add or remove a reaction with the name name
from the status with ID id
, and return a Status
entity with an updated reactions
field. The name
may be one of three formats:
- a Unicode emoji:
😎
- the
shortcode
of a local custom emoji:blobcatsunglasses
- the
shortcode
and domain of a remote custom emoji, separated by an@
:blobcatsunglasses@example.org
These endpoints correspond to the Firefish API's /notes/reactions/create
and /notes/reactions/delete
, with two differences:
- The Firefish API's
reaction
field uses leading and trailing:
for custom emojis, while the Mastodon compatibility API'sname
doesn't. - The Firefish API returns an empty HTTP 204 No Content response, while the Mastodon compatibility API returns an updated
Status
.