zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity

Add filters API

This commit is contained in:
Eugen Rochko 2018-10-05 02:49:12 +02:00
parent 8258abd6ea
commit 8774c7f9f2
2 changed files with 76 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
content/en/api/guidelines.md
View File

@ -44,3 +44,9 @@ Links in Mastodon are not shortened using URL shorteners. However, URLs in text
```
The spans with the `invisible` class can be hidden. The middle span is intended to remain visible. It may have no class if the URL is not very long, otherwise it will have an `ellipsis` class. No ellipsis (`…`) character is inserted in the markup, instead, you are expected to insert it yourself if you need it in your app.
## Filters
Clients must do their own text filtering based on filters returned from the API. The server will apply `irreversible` filters for home and notifications context, but anything else is still up to the client to filter!
Expired filters are not deleted by the server. They should no longer be applied but they are still stored by the server. It is up to clients to delete those filters eventually.

72
content/en/api/rest/filters.md
View File

@ -1,7 +1,75 @@
---
title: Filters API
title: Filters
menu:
docs:
parent: api
parent: rest-api
weight: 10
---
## GET /api/v1/filters
Text filters the user has configured that potentially must be applied client-side.
Returns array of [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="0.0.0" >}}
## POST /api/v1/filters
Create a new filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `phrase` | Keyword or phrase to filter | Required ||
| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required ||
| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional ||
| `whole_word` | Whether to consider word boundaries when matching | Optional ||
| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Null or blank string means "don't change" | Optional | Unlimited |
## GET /api/v1/filters/:id
A text filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="read read:filters" version="0.0.0" >}}
## PUT /api/v1/filters/:id
Update a text filter.
Returns [Filter]({{< relref "entities.md#filter" >}})
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}
### Parameters
|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `phrase` | Keyword or phrase to filter | Required ||
| `context` | Array of strings that means filtering context. Each string is one of `home`, `notifications`, `public`, `thread`. At least one context must be specified. | Required ||
| `irreversible` | Irreversible filtering will only work in `home` and `notifications` contexts by fully dropping the records. Otherwise, filtering is up to the client. | Optional ||
| `whole_word` | Whether to consider word boundaries when matching | Optional ||
| `expires_in` | Number that indicates seconds. Filter will be expire in seconds after API processed. Null or blank string means "don't change" | Optional | Unlimited |
## DELETE /api/v1/filters/:id
Delete a text filter.
### Resource information
{{< api_method_info auth="Yes" user="Yes" scope="write write:filters" version="0.0.0" >}}