api docs: Document GET /realm/filters.

templates/zerver/api/list-org-filters.md

@@ -0,0 +1,53 @@
+# List organization filters
+
+Fetch all the filters set up for the user's organization.
+
+`GET {{ api_url }}/v1/realm/filters`
+
+## Usage examples
+
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+<li data-language="curl">curl</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl {{ api_url }}/v1/realm/filters \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+{generate_code_example(python)|/realm/filters:get|example}
+
+</div>
+
+</div>
+
+</div>
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/realm/filters:get}
+
+## Response
+
+#### Return values
+
+* `filters`: An array of sub-arrays, each representing one of the filters set
+  up in the organization. Each of these tuples contain the pattern, the
+  formatted URL and the filter's ID, in that order. See [Create organization
+  filters](/api/create-org-filters#create-organization-filters) for details on
+  what does each field mean.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/realm/filters:get|fixture(200)}

templates/zerver/help/include/rest-endpoints.md

@@ -31,8 +31,9 @@
 
 #### Server & organizations
 
-* [Create organization filters](/api/create-org-filters)
 * [Get server settings](/api/server-settings)
+* [List organization filters](/api/list-org-filters)
+* [Create organization filters](/api/create-org-filters)
 
 #### Real-time events
 * [Real time events API](/api/real-time-events)

zerver/lib/api_test_helpers.py

@@ -154,6 +154,16 @@ def get_members(client):
     validate_against_openapi_schema(result, '/users', 'get', '200')
     assert result['members'][0]['avatar_url'] is None
 
+def get_realm_filters(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Fetch all the filters in this organization
+    result = client.get_realm_filters()
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/realm/filters', 'get', '200')
+
 def add_realm_filter(client):
     # type: (Client) -> None
 
@@ -654,6 +664,7 @@ TEST_FUNCTIONS = {
     '/users/me/subscriptions:delete': remove_subscriptions,
     '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic,
     '/users:get': get_members,
+    '/realm/filters:get': get_realm_filters,
     '/realm/filters:post': add_realm_filter,
     '/register:post': register_queue,
     '/events:delete': deregister_queue,
@@ -766,6 +777,7 @@ def test_queues(client):
 def test_server_organizations(client):
     # type: (Client) -> None
 
+    get_realm_filters(client)
     add_realm_filter(client)
     get_server_settings(client)
 

zerver/openapi/zulip.yaml

@@ -1220,6 +1220,47 @@ paths:
                           "result": "error"
                       }
   /realm/filters:
+    get:
+      description: Fetch all the filters set up for the user's organization.
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    filters:
+                      type: array
+                      items:
+                        type: array
+                        items:
+                          type:
+                            anyOf:
+                            - string
+                            - integer
+                      description: An array of sub-arrays, each representing
+                        one of the filters set up in the organization. Each of
+                        these tuples contain the pattern, the formatted URL and
+                        the filter's ID, in that order.
+                        See [Create organization
+                        filters](/api/create-org-filters#create-organization-filters)
+                        for details on what does each field mean.
+                - example:
+                    {
+                        "msg": "",
+                        "filters": [
+                            [
+                                "#(?P<id>[0-9]+)",
+                                "https://github.com/zulip/zulip/issues/%(id)s",
+                                1
+                            ]
+                        ],
+                        "result": "success"
+                    }
     post:
       description: Establish patterns in the messages that should be
         automatically linkified.