api_docs: Document "/export/realm" endpoints.

api_docs/changelog.md

@@ -910,8 +910,8 @@ No changes; feature level used for Zulip 7.0 release.
 
 **Feature level 182**
 
-* `POST /export/realm`: This endpoint now returns the ID of the data
-  export object created by the request.
+* [`POST /export/realm`](/api/export-realm): This endpoint now returns the ID
+  of the data export object created by the request.
 
 **Feature level 181**
 
@@ -2457,7 +2457,10 @@ No changes; feature level used for Zulip 3.0 release.
   window cached in a client.
 * Added `is_web_public` field to Stream objects.  This field is
   intended to support web-public streams.
-* Added `/export/realm` endpoints for triggering a data export.
+* [`GET /export/realm`](/api/get-realm-exports): Added endpoint for
+  fetching public data exports.
+  [`POST /export/realm`](/api/export-realm): Added endpoint for
+  triggering a public data export.
 * `PATCH /realm`: Added `invite_to_stream_policy`,
   `create_stream_policy`, `digest_emails_enabled`, `digest_weekday`,
   `user_group_edit_policy`, and `avatar_changes_disabled` organization settings.

api_docs/include/rest-endpoints.md

@@ -116,6 +116,8 @@
 * [Reorder custom profile fields](/api/reorder-custom-profile-fields)
 * [Create a custom profile field](/api/create-custom-profile-field)
 * [Update realm-level defaults of user settings](/api/update-realm-user-settings-defaults)
+* [Get all public data exports](/api/get-realm-exports)
+* [Create a public data export](/api/export-realm)
 
 #### Real-time events
 

zerver/openapi/python_examples.py

@@ -674,6 +674,26 @@ def remove_realm_playground(client: Client) -> None:
     validate_against_openapi_schema(result, "/realm/playgrounds/{playground_id}", "delete", "200")
 
 
+@openapi_test_function("/export/realm:get")
+def get_realm_exports(client: Client) -> None:
+    # {code_example|start}
+    # Get organization's public data exports.
+    result = client.call_endpoint(url="/export/realm", method="GET")
+    # {code_example|end}
+    assert_success_response(result)
+    validate_against_openapi_schema(result, "/export/realm", "get", "200")
+
+
+@openapi_test_function("/export/realm:post")
+def export_realm(client: Client) -> None:
+    # {code_example|start}
+    # Create a public data export of the organization.
+    result = client.call_endpoint(url="/export/realm", method="POST")
+    # {code_example|end}
+    assert_success_response(result)
+    validate_against_openapi_schema(result, "/export/realm", "post", "200")
+
+
 @openapi_test_function("/users/me:get")
 def get_profile(client: Client) -> None:
     # {code_example|start}
@@ -1810,6 +1830,8 @@ def test_server_organizations(client: Client) -> None:
     get_realm_profile_fields(client)
     reorder_realm_profile_fields(client)
     create_realm_profile_field(client)
+    export_realm(client)
+    get_realm_exports(client)
 
 
 def test_errors(client: Client) -> None:

zerver/openapi/zulip.yaml

@@ -12480,6 +12480,109 @@ paths:
       responses:
         "200":
           $ref: "#/components/responses/SimpleSuccess"
+  /export/realm:
+    get:
+      operationId: get-realm-exports
+      summary: Get all public data exports
+      tags: ["server_and_organizations"]
+      x-requires-administrator: true
+      description: |
+        Fetch all public [data exports](/help/export-your-organization)
+        of the organization.
+
+        **Changes**: New in Zulip 2.1.
+      responses:
+        "200":
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/JsonSuccessBase"
+                  - additionalProperties: false
+                    properties:
+                      result: {}
+                      msg: {}
+                      ignored_parameters_unsupported: {}
+                      exports:
+                        type: array
+                        description: |
+                          An array of dictionaries where each dictionary contains
+                          details about a public data export of the organization.
+                        items:
+                          $ref: "#/components/schemas/RealmExport"
+                    example:
+                      {
+                        "exports":
+                          [
+                            {
+                              "acting_user_id": 11,
+                              "deleted_timestamp": null,
+                              "export_time": 1722243168.134179,
+                              "export_url": "http://example.zulipchat.com/user_avatars/exports/2/FprbwiF0c_sCN0O-rf-ryFtc/zulip-export-p6yuxc45.tar.gz",
+                              "id": 323,
+                              "failed_timestamp": null,
+                              "pending": false,
+                            },
+                          ],
+                        "msg": "",
+                        "result": "success",
+                      }
+    post:
+      operationId: export-realm
+      summary: Create a public data export
+      tags: ["server_and_organizations"]
+      x-requires-administrator: true
+      description: |
+        Create a public [data export](/help/export-your-organization)
+        of the organization.
+
+        !!! warn ""
+
+            **Note**: If you're the administrator of a self-hosted installation,
+            you may be looking for the documentation on [server data export and
+            import][data-export] or [server backups][backups].
+
+        **Changes**: New in Zulip 2.1.
+
+        [data-export]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#data-export
+        [backups]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#backups
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/JsonSuccessBase"
+                  - additionalProperties: false
+                    properties:
+                      result: {}
+                      msg: {}
+                      ignored_parameters_unsupported: {}
+                      id:
+                        type: integer
+                        description: |
+                          The ID of the public data export created.
+
+                          **Changes**: New in Zulip 7.0 (feature level 182).
+                    example: {"id": 1, "result": "success", "msg": ""}
+        "400":
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "#/components/schemas/CodedError"
+                  - example:
+                      {
+                        "code": "BAD_REQUEST",
+                        "msg": "Please request a manual export from zulip-admin@example.com.",
+                        "result": "error",
+                      }
+                    description: |
+                      An example JSON error response for when the public data export
+                      exceeds the maximum allowed data export size.
   /invites:
     get:
       operationId: get-invites

zerver/tests/test_openapi.py

@@ -215,8 +215,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         ## And this one isn't, and isn't really representable
         # "/user_uploads/{realm_id_str}/{filename}",
         #### These realm administration settings are valuable to document:
-        # List data exports for organization (GET) or request one (POST)
-        "/export/realm",
         # Delete a data export.
         "/export/realm/{export_id}",
         # Manage default streams and default stream groups