openapi: Document apns_device_token endpoints.

This commit adds API documentation for "/users/me/apns_device_token:post"
and "/users/me/apns_device_token:delete" endpoints.

openapi: Document android_gcm_reg_id endpoints.

Co-authored-by: Suyash Vardhan Mathur <suyash.mathur@research.iiit.ac.in>

api_docs/changelog.md

@@ -339,7 +339,7 @@ No changes; feature level used for Zulip 8.0 release.
 
 **Feature level 223**
 
-* `POST /users/me/apns_device_token`:
+* [`POST /users/me/apns_device_token`](/api/add-apns-token):
   The `appid` parameter is now required.
   Previously it defaulted to the server setting `ZULIP_IOS_APP_ID`,
   defaulting to "org.zulip.Zulip".

api_docs/include/rest-endpoints.md

@@ -125,3 +125,5 @@
 * [Fetch an API key (production)](/api/fetch-api-key)
 * [Fetch an API key (development only)](/api/dev-fetch-api-key)
 * [Send a test notification to mobile device(s)](/api/test-notify)
+* [Add an APNs device token](/api/add-apns-token)
+* [Remove an APNs device token](/api/remove-apns-token)

zerver/openapi/python_examples.py

@@ -1367,6 +1367,30 @@ def get_stream_topics(client: Client, stream_id: int) -> None:
     validate_against_openapi_schema(result, "/users/me/{stream_id}/topics", "get", "200")
 
 
+@openapi_test_function("/users/me/apns_device_token:post")
+def add_apns_token(client: Client) -> None:
+    # {code_example|start}
+    request = {"token": "apple-tokenbb", "appid": "org.zulip.Zulip"}
+    result = client.call_endpoint(url="/users/me/apns_device_token", method="POST", request=request)
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, "/users/me/apns_device_token", "post", "200")
+
+
+@openapi_test_function("/users/me/apns_device_token:delete")
+def remove_apns_token(client: Client) -> None:
+    # {code_example|start}
+    request = {
+        "token": "apple-tokenbb",
+    }
+    result = client.call_endpoint(
+        url="/users/me/apns_device_token", method="DELETE", request=request
+    )
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, "/users/me/apns_device_token", "delete", "200")
+
+
 @openapi_test_function("/typing:post")
 def set_typing_status(client: Client) -> None:
     ensure_users([10, 11], ["hamlet", "iago"])
@@ -1656,6 +1680,8 @@ def test_users(client: Client, owner_client: Client) -> None:
     get_alert_words(client)
     add_alert_words(client)
     remove_alert_words(client)
+    add_apns_token(client)
+    remove_apns_token(client)
 
 
 def test_streams(client: Client, nonadmin_client: Client) -> None:

zerver/openapi/zulip.yaml

@@ -10039,7 +10039,118 @@ paths:
                           }
                         description: |
                           An example JSON response for when the user is not previously muted:
+  /users/me/apns_device_token:
+    post:
+      operationId: add-apns-token
+      summary: Add an APNs device token
+      tags: ["users"]
+      description: |
+        This endpoint adds an APNs device token to register for iOS push notifications.
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                token:
+                  description: |
+                    The token provided by the device.
+                  type: string
+                  example: apple-tokenbb
+                appid:
+                  description: |
+                    The ID of the Zulip app that is making the request.
 
+                    **Changes**: In Zulip 8.0 (feature level 223), this parameter was made
+                    required. Previously, if it was unspecified, the server would use a default
+                    value (based on the `ZULIP_IOS_APP_ID` server setting, which
+                    defaulted to `"org.zulip.Zulip"`).
+                  type: string
+                  example: org.zulip.Zulip
+              required:
+                - token
+                - appid
+      responses:
+        "200":
+          $ref: "#/components/responses/SimpleSuccess"
+        "400":
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - allOf:
+                      - $ref: "#/components/schemas/CodedError"
+                      - description: |
+                          A typical failed JSON response for when the token's length is invalid
+                          or it is empty:
+                        example:
+                          {
+                            "result": "error",
+                            "msg": "Empty or invalid length token",
+                            "code": "BAD_REQUEST",
+                          }
+                  - allOf:
+                      - $ref: "#/components/schemas/CodedError"
+                      - example:
+                          {
+                            "result": "error",
+                            "msg": "Invalid APNS token",
+                            "code": "BAD_REQUEST",
+                          }
+                        description: |
+                          A typical failed JSON response for when the APNs token is invalid:
+    delete:
+      operationId: remove-apns-token
+      summary: Remove an APNs device token
+      tags: ["users"]
+      description: |
+        This endpoint removes an APNs device token for iOS push notifications.
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                token:
+                  description: |
+                    The token provided by the device.
+                  type: string
+                  example: apple-tokenbb
+              required:
+                - token
+      responses:
+        "200":
+          $ref: "#/components/responses/SimpleSuccess"
+        "400":
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - allOf:
+                      - $ref: "#/components/schemas/CodedError"
+                      - description: |
+                          A typical failed JSON response for when the token's length is invalid
+                          or it is empty:
+                        example:
+                          {
+                            "result": "error",
+                            "msg": "Empty or invalid length token",
+                            "code": "BAD_REQUEST",
+                          }
+                  - allOf:
+                      - $ref: "#/components/schemas/CodedError"
+                      - example:
+                          {
+                            "result": "error",
+                            "msg": "Token does not exist",
+                            "code": "BAD_REQUEST",
+                          }
+                        description: |
+                          A typical failed JSON response for when the token does not exist:
   /users/{user_id}/subscriptions/{stream_id}:
     get:
       operationId: get-subscription-status

zerver/tests/test_openapi.py

@@ -250,7 +250,6 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         "/dev_list_users",
         # Registration for iOS/Android mobile push notifications.
         "/users/me/android_gcm_reg_id",
-        "/users/me/apns_device_token",
         #### These personal settings endpoints have modest value to document:
         "/users/me/avatar",
         "/users/me/api_key/regenerate",