From 4a0f7df6a97e9d1a3fbba09e9bba91e7406eb4d4 Mon Sep 17 00:00:00 2001
From: tateisu <tateisu@gmail.com>
Date: Tue, 17 Jul 2018 05:09:12 +0900
Subject: [PATCH] (API) Filters (#647)

* (API) follow suggestions

* fixup

* (api)keyword filter

* fixup
---
 Using-the-API/API.md           | 67 ++++++++++++++++++++++++++++++++++
 Using-the-API/Streaming-API.md |  4 +-
 2 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/Using-the-API/API.md b/Using-the-API/API.md
index eb4ff212..0034d40a 100644
--- a/Using-the-API/API.md
+++ b/Using-the-API/API.md
@@ -11,6 +11,7 @@ API overview
   - [Blocks](#blocks)
   - [Domain blocks](#domain-blocks)
   - [Favourites](#favourites)
+  - [Filters](#filters)
   - [Follow Requests](#follow-requests)
   - [Follow Suggestions](#follow-suggestions)
   - [Follows](#follows)
@@ -32,6 +33,7 @@ API overview
   - [Context](#context)
   - [Emoji](#emoji)
   - [Error](#error)
+  - [Filter](#filter)
   - [Instance](#instance)
   - [List](#list)
   - [Mention](#mention)
@@ -332,6 +334,52 @@ Query parameters:
 
 Returns an array of [Statuses](#status) favourited by the authenticated user.
 
+### Filters
+
+####  Fetching a list of filters:
+
+    GET /api/v1/filters
+
+> **Note:** This API does not provide pagenation.
+
+Returns an array of [Filters](#filter).
+
+#### Creating a filter.
+
+    POST /api/v1/filters
+
+| Field             | Description                                                         | Optional   |
+| ----------------- | ------------------------------------------------------------------- | ---------- |
+| `phrase`          | String that contains keyword or phrase         | no         |
+| `context`         | Array of strings that means filtering context. each string is one of 'home', 'notifications', 'public', 'thread'. At least one context must be specified | no.         |
+| `irreversible`           | Boolean that indicates irreversible filtering on server side       | yes        |
+| `whole_word`           | Boolean that indicates word match.     | yes        |
+| `expires_in`           | Number that indicates seconds. Filter will be expire in seconds after API processed. null or blank string means "don't change". default is unlimited. | yes        |
+
+Returns a [Filter](#filter).
+
+#### Get a filter.
+
+    GET /api/v1/filters/:id
+
+Returns a [Filter](#filter).
+
+#### Update a filter.
+
+    PUT /api/v1/filters/:id
+
+The parameter is same with 'POST /api/v1/filters'.
+
+> **Note:** Currently there is noway to remove expires from existing filter.
+
+Returns a [Filter](#filter).
+
+#### Delete a filter.
+
+    DELETE /api/v1/filters/:id
+
+Returns a empty object.
+
 ### Follow Requests
 
 #### Fetching a list of follow requests:
@@ -895,6 +943,25 @@ The most important part of an error response is the HTTP status code. Standard s
 | ------------------------ | ---------------------------------- | -------- |
 | `error`                  | A textual description of the error | no       |
 
+### Filter
+
+| Attribute                | Description                        | Nullable |
+| ------------------------ | ---------------------------------- | -------- |
+| `id`                  | ID of the filter | no       |
+| `phrase`                  | Keyword or phrase | no       |
+| `context`                  | Array of strings that indicate filter context. each string is ont of 'home', 'notifications', 'public', 'thread'  | no       |
+| `expires_at`                  | String such as "2018-07-06T00:59:13.161Z" that indicates when this filter is expired.  | yes       |
+| `irreversible`                  | Boolean that indicates irreversible server side filtering. | no       |
+| `whole_word`                  | Boolean that indicates word match.  | no       |
+
+If `whole_word` is true , client app should do:
+- Define 'Word constituent character' for your app. In official implementation, it's [A-Za-z0-9_] for JavaScript, it's [[:word:]] for Ruby. In Ruby case it's POSIX character class (Letter | Mark | Decimal_Number | Connector_Punctuation). 
+- If the phrase starts with word character, and if the previous character before matched range is word character, its matched range should treat to not match.
+- If the phrase ends with word character, and if the next character after matched range is word character, its matched range should treat to not match.
+
+Please check app/javascript/mastodon/selectors/index.js and app/lib/feed_manager.rb for more details.
+Most case client apps are compared to WebUI(JS), they should obey to JS implementation.
+
 ### Instance
 
 | Attribute                | Description                                                              | Nullable |
diff --git a/Using-the-API/Streaming-API.md b/Using-the-API/Streaming-API.md
index 137b5b72..888352f7 100644
--- a/Using-the-API/Streaming-API.md
+++ b/Using-the-API/Streaming-API.md
@@ -32,7 +32,6 @@ The stream will contain events as well as heartbeat comments. Lines that begin w
 ```
 event: name
 data: payload
-
 ```
 
 [See MDN](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format)
@@ -44,5 +43,8 @@ data: payload
 |`update`|A new status has appeared!|Status|
 |`notification`|A new notification|Notification|
 |`delete`|A status has been deleted|ID of the deleted status|
+|`filters_changed`|Keyword filters have been changed|Not exists. (undefined)|
 
 The payload is JSON-encoded.
+
+> **Note:** In case of  `filters_changed` event, `payload` is not defined.