api docs: Document the GET /messages/<message_id> endpoint.

templates/zerver/api/get-raw-message.md

@@ -0,0 +1,60 @@
+# Get a raw message
+
+Get the raw content of a message.
+
+`GET {{ api_url }}/v1/messages/<msg_id>`
+
+This is a rarely-used endpoint relevant for clients that primarily
+work with HTML-rendered messages but might need to occasionally fetch
+the message's raw markdown (e.g. for pre-filling a message-editing
+UI).
+
+## Usage examples
+
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+<li data-language="curl">curl</li>
+</ul>
+<div class="blocks">
+
+<div data-language="curl" markdown="1">
+
+```
+curl {{ api_url }}/v1/messages/<msg_id> \
+    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
+```
+
+</div>
+
+<div data-language="python" markdown="1">
+
+{generate_code_example(python)|/messages/{message_id}:get|example}
+
+</div>
+
+</div>
+
+</div>
+
+## Arguments
+
+{generate_api_arguments_table|zulip.yaml|/messages/{message_id}:get}
+
+## Response
+
+#### Return values
+
+* `raw_content`: The raw content of the message.
+
+#### Example response
+
+A typical successful JSON response may look like:
+
+{generate_code_example|/messages/{message_id}:get|fixture(200)}
+
+An example JSON response for when the specified message does not exist or it
+is not visible to the user making the query (e.g. it was a PM between other
+two users):
+
+{generate_code_example|/messages/{message_id}:get|fixture(400)}

templates/zerver/help/include/rest-endpoints.md

@@ -1,6 +1,7 @@
 #### Messages
 
 * [Get messages](/api/get-messages)
+* [Get a raw message](/api/get-raw-message)
 * [Send a message](/api/send-message)
 * [Update a message](/api/update-message)
 * [Render a message](/api/render-message)

zerver/lib/api_test_helpers.py

@@ -344,6 +344,19 @@ def get_messages(client):
     validate_against_openapi_schema(result, '/messages', 'get', '200')
     assert len(result['messages']) <= request['num_before']
 
+def get_raw_message(client, message_id):
+    # type: (Client, int) -> None
+
+    assert int(message_id)
+
+    # {code_example|start}
+    # Get the raw content of the message with ID "message_id"
+    result = client.get_raw_message(message_id)
+    # {code_example|end}
+
+    validate_against_openapi_schema(result, '/messages/{message_id}', 'get',
+                                    '200')
+
 def send_message(client):
     # type: (Client) -> int
 
@@ -580,6 +593,7 @@ TEST_FUNCTIONS = {
     '/messages/render:post': render_message,
     '/messages:get': get_messages,
     '/messages:post': send_message,
+    '/messages/{message_id}:get': get_raw_message,
     '/messages/{message_id}:patch': update_message,
     '/get_stream_id:get': get_stream_id,
     'get-subscribed-streams': list_subscriptions,
@@ -652,6 +666,7 @@ def test_messages(client, nonadmin_client):
     render_message(client)
     message_id = send_message(client)
     update_message(client, message_id)
+    get_raw_message(client, message_id)
     get_messages(client)
 
     test_nonexistent_stream_error(client)

zerver/openapi/zulip-2.0.yaml

@@ -249,33 +249,6 @@ paths:
             $ref: '#/definitions/MessageResponse'
 
   /messages/{message_id}:
-    get:
-      description: Retrieve the content of a message.
-      parameters:
-      - name: message_id
-        in: path
-        description: ID of the message to be retrieved.
-        type: integer
-        required: true
-      security:
-      - basicAuth: []
-      responses:
-        '200':
-          description: Success.
-          schema:
-            type: object
-            required:
-            - msg
-            - result
-            - raw_content
-            properties:
-              msg:
-                type: string
-              result:
-                type: string
-              raw_content:
-                type: string
-                description: Body of the queried message.
     patch:
       description: Edit a message that has already been sent.
       parameters:

zerver/openapi/zulip.yaml

@@ -467,6 +467,42 @@ paths:
                         "result": "error"
                     }
   /messages/{message_id}:
+    get:
+      description: Get the raw content of a message.
+      parameters:
+      - name: message_id
+        in: path
+        description: The target message's ID.
+        schema:
+          type: integer
+        example: 42
+        required: true
+      security:
+      - basicAuth: []
+      responses:
+        '200':
+          description: Success.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonSuccess'
+                - properties:
+                    raw_content:
+                      type: string
+                      description: The raw content of the message.
+                - example:
+                    {
+                        "raw_content": "**Don't** forget your towel!",
+                        "result": "success",
+                        "msg": ""
+                    }
+        '400':
+          description: Bad request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InvalidMessageError'
     patch:
       description: Edit a message that has already been sent.
       parameters:
@@ -1476,6 +1512,19 @@ components:
               "queue_id": "1518820930:1",
               "result": "error"
           }
+    InvalidMessageError:
+      allOf:
+      - $ref: '#/components/schemas/JsonSuccess'
+      - properties:
+          raw_content:
+            type: string
+            description: The raw content of the message.
+      - example:
+          {
+              "msg": "Invalid message(s)",
+              "code": "BAD_REQUEST",
+              "result": "error"
+          }
     NonExistingStreamError:
       allOf:
         - $ref: '#/components/schemas/CodedError'