api_documentation: Document "/invites/multiuse/{invite_id}" endpoint.

api_docs/changelog.md

@@ -521,9 +521,9 @@ No changes; feature level used for Zulip 8.0 release.
   therefore the response did not include reusable invitation links for these
   users.
 
-* `DELETE /invites/multiuse/{invite_id}`: Non-admin users can now revoke
-  reusable invitation links they have created. Previously, only admin users could
-  create and revoke reusable invitation links.
+* [`DELETE /invites/multiuse/{invite_id}`](/api/revoke-invite-link): Non-admin
+  users can now revoke reusable invitation links they have created. Previously,
+  only admin users could create and revoke reusable invitation links.
 
 * [`GET /events`](/api/get-events): When the set of invitations in an
   organization changes, an `invites_changed` event is now sent to the

api_docs/include/rest-endpoints.md

@@ -94,6 +94,7 @@
 * [Send invitations](/api/send-invites)
 * [Create a reusable invitation link](/api/create-invite-link)
 * [Revoke an email invitation](/api/revoke-email-invite)
+* [Revoke a reusable invitation link](/api/revoke-invite-link)
 
 #### Server & organizations
 

zerver/openapi/python_examples.py

@@ -363,6 +363,24 @@ def revoke_email_invitation(client: Client) -> None:
     validate_against_openapi_schema(result, "/invites/{invite_id}", "delete", "200")
 
 
+@openapi_test_function("/invites/multiuse/{invite_id}:delete")
+def revoke_reusable_invitation_link(client: Client) -> None:
+    request = {
+        "invite_expires_in_minutes": 14400,  # 10 days
+        "invite_as": 400,
+        "stream_ids": [1, 8, 9],
+    }
+    result = client.call_endpoint(url="/invites/multiuse", method="POST", request=request)
+
+    # {code_example|start}
+    # Revoke reusable invitation link
+    invite_id = 2
+    result = client.call_endpoint(url=f"/invites/multiuse/{invite_id}", method="DELETE")
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, "/invites/multiuse/{invite_id}", "delete", "200")
+
+
 @openapi_test_function("/users/{user_id}:get")
 def get_single_user(client: Client) -> None:
     ensure_users([8], ["cordelia"])
@@ -1774,6 +1792,7 @@ def test_invitations(client: Client) -> None:
     send_invitations(client)
     revoke_email_invitation(client)
     create_reusable_invitation_link(client)
+    revoke_reusable_invitation_link(client)
     get_invitations(client)
 
 

zerver/openapi/zulip.yaml

@@ -12471,6 +12471,58 @@ paths:
                           }
                         description: |
                           A typical failed JSON response for an invalid email invitation ID:
+  /invites/multiuse/{invite_id}:
+    delete:
+      operationId: revoke-invite-link
+      summary: Revoke a reusable invitation link
+      tags: ["invites"]
+      description: |
+        Revoke a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link).
+
+        A user can only revoke [invitations that they can
+        manage](/help/invite-new-users#manage-pending-invitations).
+
+        **Changes**: Prior to Zulip 8.0 (feature level 209), only organization
+        administrators were able to create and revoke reusable invitation links.
+      parameters:
+        - name: invite_id
+          in: path
+          description: |
+            The ID of the reusable invitation link to be revoked.
+          schema:
+            type: integer
+          example: 1
+          required: true
+      responses:
+        "200":
+          $ref: "#/components/responses/SimpleSuccess"
+        "400":
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - allOf:
+                      - $ref: "#/components/schemas/CodedError"
+                      - example:
+                          {
+                            "result": "error",
+                            "msg": "No such invitation",
+                            "code": "BAD_REQUEST",
+                          }
+                        description: |
+                          A typical failed JSON response for an invalid invitation link ID:
+                  - allOf:
+                      - $ref: "#/components/schemas/CodedError"
+                      - example:
+                          {
+                            "result": "error",
+                            "msg": "Invitation has already been revoked",
+                            "code": "BAD_REQUEST",
+                          }
+                        description: |
+                          A typical failed JSON response for when the invitation link has already
+                          been revoked:
   /register:
     post:
       operationId: register-queue

zerver/tests/test_openapi.py

@@ -240,7 +240,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         "/default_stream_groups/{group_id}/streams",
         # Administer invitations
         "/invites/{prereg_id}/resend",
-        "/invites/multiuse/{invite_id}",
         # Single-stream settings alternative to the bulk endpoint
         # users/me/subscriptions/properties; probably should just be a
         # section of the same page.