Various missing information

[anosidium]

The documentation is missing some information.

Entity Notification, type attribute is missing annual_report string as part of its enumeration. I received a special annual report notification. It broke my client.

Likewise AnnualReport entity exists but the documentation does not list it.

As far as I was able to gather, it includes year attribute and an optional account attribute.

Also, entity NotificationGroup needs to include an optional annual_report attribute which I believe is an AnnualReport type.

[trwnh]

See #1211 -- 4.3 "annual_reports" feature is on the list of undocumented things

[anosidium]

How are clients supposed to guard against these undocumented APIs when they are received in the JSON response?

[trwnh]

At the very least for the notifications API, several clients show a "notification of unknown type" item in their notification UIs. I would say that the notification handler could be thought of as a case-based structure:

• If it's a mention, render a mention notification
• If it's a favourite, render a favourite notification
• ...
• By default case, render a generic notification

[anosidium]

Right but what about the content of the notification? As far as I have inspected, it doesn't provide a status to indicate what the notification actually is. It returns an account but there is no context provided. How do I inform the user that this notification is an annual report notification that they can view their report even if I were to display it as an unmarked notification?

[trwnh]

You can generally expect a type and a created_at for now: https://github.com/mastodon/mastodon/blob/72a4da83fdd2ac8a089cde208149792108783d97/app/serializers/rest/notification_serializer.rb#L5

This could be rendered as a single line of text that says: "Unknown notification received: {type}"

If you're talking about how to handle notifications of type annual_report, then I think you're supposed to use GET /api/v1/annual_reports (and the notification is just to tell you that the report is ready).