Skip to content

armgit / zulip

Public Imported from GitHub
0

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

api-docs: Document POST /realm/deactivate.

Agnish Bauri43172928c3fa
diff --git a/api_docs/changelog.md b/api_docs/changelog.md
index 34da4f587d0..dd9045c5c99 100644
--- a/api_docs/changelog.md
+++ b/api_docs/changelog.md
@@ -1643,9 +1643,9 @@ No changes; feature level used for Zulip 10.0 release.
`server_max_deactivated_realm_deletion_days` fields for the permitted
number of days before full data deletion of a deactivated organization
on the server.
-* `POST /realm/deactivate`: Added `deletion_delay_days` parameter to
- support setting when a full data deletion of the deactivated
- organization may be done.
+* [`POST /realm/deactivate`](/api/deactivate-realm): Added
+ `deletion_delay_days` parameter to support setting when a full data
+ deletion of the deactivated organization may be done.
**Feature level 331**
diff --git a/api_docs/include/rest-endpoints.md b/api_docs/include/rest-endpoints.md
index 7c102bba95c..1cfc347f78c 100644
--- a/api_docs/include/rest-endpoints.md
+++ b/api_docs/include/rest-endpoints.md
@@ -160,6 +160,7 @@
* [Create a data export](/api/export-realm)
* [Get data export consent state](/api/get-realm-export-consents)
* [Test welcome bot custom message](/api/test-welcome-bot-custom-message)
+* [Deactivate an organization](/api/deactivate-realm)
## Real-time events
diff --git a/zerver/openapi/test_curl_examples.py b/zerver/openapi/test_curl_examples.py
index f6a3aae6dd5..4ce28a079d7 100644
--- a/zerver/openapi/test_curl_examples.py
+++ b/zerver/openapi/test_curl_examples.py
@@ -40,6 +40,10 @@ UNTESTED_GENERATED_CURL_EXAMPLES = {
"create-constructor-groups-video-call",
"create-nextcloud-talk-video-call",
"create-webex-video-call",
+ # Successfully running this example would deactivate the "zulip"
+ # realm used by the test server, breaking the curl examples that
+ # run after it.
+ "deactivate-realm",
}
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index 4e66dcf11e9..2bb4067b39c 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -15050,6 +15050,121 @@ paths:
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
+ /realm/deactivate:
+ post:
+ operationId: deactivate-realm
+ summary: Deactivate an organization
+ tags: ["server_and_organizations"]
+ description: |
+ [Deactivate an organization](/help/deactivate-your-organization) on the
+ Zulip server. Deactivating an organization immediately logs out all of
+ its users and prevents them from logging in again.
+
+ A deactivated organization can be reactivated via a [management
+ command](https://zulip.readthedocs.io/en/latest/production/management-commands.html),
+ unless its data has been permanently deleted (see the
+ [`deletion_delay_days` parameter](/api/deactivate-realm#parameter-deletion_delay_days)
+ below).
+
+ This endpoint is primarily useful for Zulip servers that host
+ [multiple organizations](https://zulip.readthedocs.io/en/latest/production/multiple-organizations.html).
+ x-requires-owner: true
+ requestBody:
+ content:
+ application/x-www-form-urlencoded:
+ schema:
+ type: object
+ additionalProperties: false
+ properties:
+ deletion_delay_days:
+ type: integer
+ nullable: true
+ description: |
+ The number of days to wait before permanently deleting all
+ of the deactivated organization's data (users, channels,
+ messages, etc.).
+
+ A value of `0` will delete the organization's data
+ immediately, which means that the organization cannot be
+ reactivated. A `null` value indicates that the organization's
+ data will not be deleted, but rather retained indefinitely.
+
+ Valid values for this parameter are limited to the range
+ permitted by the server, indicated by the
+ `server_min_deactivated_realm_deletion_days` and
+ `server_max_deactivated_realm_deletion_days` fields in the
+ [`POST /register`](/api/register-queue) response. A value of
+ `null` is only permitted when
+ `server_max_deactivated_realm_deletion_days` is `null`. A
+ value of `0` is only permitted when
+ `server_min_deactivated_realm_deletion_days` is `null`.
+
+ These limits do not apply to
+ [Zulip Cloud demo organizations](/help/demo-organizations),
+ for which this parameter is instead required: it must be `0`
+ when the organization owner has not configured an email
+ address, and otherwise must not exceed the number of days
+ remaining before the demo organization's scheduled deletion.
+
+ **Changes**: New in Zulip 10.0 (feature level 332).
+ example: 30
+ encoding:
+ deletion_delay_days:
+ contentType: application/json
+ responses:
+ "200":
+ $ref: "#/components/responses/SimpleSuccess"
+ "400":
+ description: Bad request.
+ content:
+ application/json:
+ schema:
+ oneOf:
+ - allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - description: |
+ An example JSON response for when the current user is
+ not an organization owner:
+ example:
+ {
+ "code": "UNAUTHORIZED_PRINCIPAL",
+ "msg": "Must be an organization owner",
+ "result": "error",
+ }
+ - allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - description: |
+ An example JSON response for when `deletion_delay_days`
+ is below the minimum permitted by the server:
+ example:
+ {
+ "code": "BAD_REQUEST",
+ "msg": "Data deletion time must be at least 14 days in the future.",
+ "result": "error",
+ }
+ - allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - description: |
+ An example JSON response for when `deletion_delay_days`
+ exceeds the maximum permitted by the server:
+ example:
+ {
+ "code": "BAD_REQUEST",
+ "msg": "Data deletion time must be at most 30 days in the future.",
+ "result": "error",
+ }
+ - allOf:
+ - $ref: "#/components/schemas/CodedError"
+ - description: |
+ An example JSON response for when an invalid
+ `deletion_delay_days` is given for a
+ [Zulip Cloud demo organization](/help/demo-organizations):
+ example:
+ {
+ "code": "BAD_REQUEST",
+ "msg": "Invalid data deletion time for demo organization.",
+ "result": "error",
+ }
/realm/profile_fields:
get:
operationId: get-custom-profile-fields
diff --git a/zerver/tests/test_openapi.py b/zerver/tests/test_openapi.py
index 9e406dd420b..a5c34a1e243 100644
--- a/zerver/tests/test_openapi.py
+++ b/zerver/tests/test_openapi.py
@@ -233,7 +233,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
"/realm/profile_fields/{field_id}",
"/realm/icon",
"/realm/logo",
- "/realm/deactivate",
"/realm/subdomain/{subdomain}",
# API for Zoom video calls. Unclear if this can support other apps.
"/calls/zoom/create",