Add documentation for `/api/v2/notifications/policy` (#1503)
* Rename `NotificationPolicy` entity to `V1::NotificationPolicy` * Add documentation for v2 NotificationPolicy * Add deprecation warning
This commit is contained in:
Claire
GitHub
parent
d1899d20fb
commit
b59b7fea62
|
|
@ -11,31 +11,38 @@ aliases: [
|
|||
|
||||
## Attributes
|
||||
|
||||
### `filter_not_following` {#filter_not_following}
|
||||
### `for_not_following` {#for_not_following}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts the user is not following.\
|
||||
**Type:** Boolean\
|
||||
**Description:** Whether to `accept`, `filter` or `drop` notifications from accounts the user is not following. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.\
|
||||
**Type:** String (one of `accept`, `filter` or `drop`)\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_not_followers` {#filter_not_followers}
|
||||
### `for_not_followers` {#for_not_followers}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts that are not following the user.\
|
||||
**Type:** Boolean\
|
||||
**Description:** Whether to `accept`, `filter` or `drop` notifications from accounts that are not following the user. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.\
|
||||
**Type:** String (one of `accept`, `filter` or `drop`)\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_new_accounts` {#filter_new_accounts}
|
||||
### `for_new_accounts` {#for_new_accounts}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts created in the past 30 days.\
|
||||
**Type:** Boolean\
|
||||
**Description:** Whether to `accept`, `filter` or `drop` notifications from accounts created in the past 30 days. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.\
|
||||
**Type:** String (one of `accept`, `filter` or `drop`)\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_private_mentions` {#filter_private_mentions}
|
||||
### `for_private_mentions` {#for_private_mentions}
|
||||
|
||||
**Description:** Whether to filter notifications from private mentions. Replies to private mentions initiated by the user, as well as accounts the user follows, are never filtered.\
|
||||
**Type:** Boolean\
|
||||
**Description:** Whether to `accept`, `filter` or `drop` notifications from private mentions. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing. Replies to private mentions initiated by the user, as well as accounts the user follows, are always allowed, regardless of this value.\
|
||||
**Type:** String (one of `accept`, `filter` or `drop`)\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `for_limited_accounts` {#for_limited_accounts}
|
||||
|
||||
**Description:** Whether to `accept`, `filter` or `drop` notifications from accounts that were limited by a moderator. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
||||
**Type:** String (one of `accept`, `filter` or `drop`)\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
|
|
@ -65,10 +72,11 @@ aliases: [
|
|||
```json
|
||||
|
||||
{
|
||||
"filter_not_following": false,
|
||||
"filter_not_followers": false,
|
||||
"filter_new_accounts": false,
|
||||
"filter_private_mentions": true,
|
||||
"for_not_following": "accept",
|
||||
"for_not_followers": "accept",
|
||||
"for_new_accounts": "accept",
|
||||
"for_private_mentions": "drop",
|
||||
"for_limited_accounts": "filter",
|
||||
"summary": {
|
||||
"pending_requests_count": 0,
|
||||
"pending_notifications_count": 0
|
||||
|
|
@ -82,6 +90,3 @@ aliases: [
|
|||
{{< page-relref ref="methods/notifications" caption="notifications API methods" >}}
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_policy_serializer.rb" caption="app/serializers/rest/notification_policy_serializer.rb" >}}
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,90 @@
|
|||
---
|
||||
title: V1::NotificationPolicy
|
||||
description: Represents the notification filtering policy of the user.
|
||||
menu:
|
||||
docs:
|
||||
parent: entities
|
||||
aliases: [
|
||||
"/entities/v1_NotificationPolicy",
|
||||
]
|
||||
---
|
||||
|
||||
{{< hint style="warning" >}}
|
||||
This version of the notification filtering policy API is deprecated and has not shipped in any release. Please refer to the [current version]({{< relref "entities/NotificationPolicy">}}) instead.
|
||||
{{</ hint >}}
|
||||
|
||||
## Attributes
|
||||
|
||||
### `filter_not_following` {#filter_not_following}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts the user is not following.\
|
||||
**Type:** Boolean\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_not_followers` {#filter_not_followers}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts that are not following the user.\
|
||||
**Type:** Boolean\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_new_accounts` {#filter_new_accounts}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts created in the past 30 days.\
|
||||
**Type:** Boolean\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_private_mentions` {#filter_private_mentions}
|
||||
|
||||
**Description:** Whether to filter notifications from private mentions. Replies to private mentions initiated by the user, as well as accounts the user follows, are never filtered.\
|
||||
**Type:** Boolean\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `summary` {#summary}
|
||||
|
||||
**Description:** Summary of the filtered notifications
|
||||
**Type:** Hash\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `summary[pending_requests_count]` {#pending_requests_count}
|
||||
|
||||
**Description:** Number of different accounts from which the user has non-dismissed filtered notifications. Capped at 100.
|
||||
**Type:** Integer\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `summary[pending_notifications_count]` {#pending_notifications_count}
|
||||
|
||||
**Description:** Number of total non-dismissed filtered notifications. May be inaccurate.
|
||||
**Type:** Integer\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
|
||||
{
|
||||
"filter_not_following": false,
|
||||
"filter_not_followers": false,
|
||||
"filter_new_accounts": false,
|
||||
"filter_private_mentions": true,
|
||||
"summary": {
|
||||
"pending_requests_count": 0,
|
||||
"pending_notifications_count": 0
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
{{< page-relref ref="entities/NotificationPolicy" caption="NotificationPolicy (for the released version)" >}}
|
||||
|
||||
{{< page-relref ref="methods/notifications" caption="notifications API methods" >}}
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/v1/notification_policy_serializer.rb" caption="app/serializers/rest/v1/notification_policy_serializer.rb" >}}
|
||||
|
|
@ -454,7 +454,7 @@ Invalid or missing Authorization header.
|
|||
## Get the filtering policy for notifications {#get-policy}
|
||||
|
||||
```http
|
||||
GET /api/v1/notifications/policy HTTP/1.1
|
||||
GET /api/v2/notifications/policy HTTP/1.1
|
||||
```
|
||||
|
||||
Notifications filtering policy for the user.
|
||||
|
|
@ -479,10 +479,11 @@ The response body contains the current notifications filtering policy for the us
|
|||
|
||||
```json
|
||||
{
|
||||
"filter_not_following": false,
|
||||
"filter_not_followers": false,
|
||||
"filter_new_accounts": false,
|
||||
"filter_private_mentions": true,
|
||||
"for_not_following": "accept",
|
||||
"for_not_followers": "accept",
|
||||
"for_new_accounts": "accept",
|
||||
"for_private_mentions": "drop",
|
||||
"for_limited_accounts": "filter",
|
||||
"summary": {
|
||||
"pending_requests_count": 0,
|
||||
"pending_notifications_count": 0
|
||||
|
|
@ -503,7 +504,7 @@ Invalid or missing Authorization header.
|
|||
## Update the filtering policy for notifications
|
||||
|
||||
```http
|
||||
PATCH /api/v1/notifications/policy HTTP/1.1
|
||||
PATCH /api/v2/notifications/policy HTTP/1.1
|
||||
```
|
||||
|
||||
Update the user's notifications filtering policy.
|
||||
|
|
@ -522,17 +523,20 @@ Authorization
|
|||
|
||||
#### Form data parameters
|
||||
|
||||
filter_not_following
|
||||
: Boolean. Whether to filter notifications from accounts the user is not following.
|
||||
for_not_following
|
||||
: String. Whether to `accept`, `filter` or `drop` notifications from accounts the user is not following. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
||||
|
||||
filter_not_followers
|
||||
: Boolean. Whether to filter notifications from accounts that are not following the user.
|
||||
for_not_followers
|
||||
: String. Whether to `accept`, `filter` or `drop` notifications from accounts that are not following the user. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
||||
|
||||
filter_new_accounts
|
||||
: Boolean. Whether to filter notifications from accounts created in the past 30 days.
|
||||
for_new_accounts
|
||||
: String. Whether to `accept`, `filter` or `drop` notifications from accounts created in the past 30 days. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
||||
|
||||
filter_private_mentions
|
||||
: Boolean. Whether to filter notifications from private mentions. Replies to private mentions initiated by the user, as well as accounts the user follows, are never filtered.
|
||||
for_private_mentions
|
||||
: String. Whether to `accept`, `filter` or `drop` notifications from private mentions. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing. Replies to private mentions initiated by the user, as well as accounts the user follows, are always allowed, regardless of this value.
|
||||
|
||||
for_limited_accounts
|
||||
: String. Whether to `accept`, `filter` or `drop` notifications from accounts that were limited by a moderator. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
||||
|
||||
|
||||
#### Response
|
||||
|
|
|
|||
Loading…
Reference in New Issue