diff --git a/api_docs/changelog.md b/api_docs/changelog.md index ed94acfed2..44ca4db5f8 100644 --- a/api_docs/changelog.md +++ b/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. diff --git a/api_docs/include/rest-endpoints.md b/api_docs/include/rest-endpoints.md index 1b9edd2093..856655593c 100644 --- a/api_docs/include/rest-endpoints.md +++ b/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 diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py index 50cf1f8aa6..cca31a7580 100644 --- a/zerver/openapi/python_examples.py +++ b/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: diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 7d1ec4828f..4ca14ce934 100644 --- a/zerver/openapi/zulip.yaml +++ b/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 diff --git a/zerver/tests/test_openapi.py b/zerver/tests/test_openapi.py index 389cced6cd..8d04280b31 100644 --- a/zerver/tests/test_openapi.py +++ b/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