api docs: Improve headings and organization for endpoints.

Mostly, this is a change in ordering to make more sense, but we also
fix several names that were clearly confusing.

We restore the convention that each endpoint has the same title at the
top of the page as what we have in the sidebar menu, which appears to
have been violated in many recent updates to API documentation.

templates/zerver/api/add-linkifier.md

@@ -1,4 +1,4 @@
-# Create linkifiers
+# Add a linkifier
 
 {generate_api_description(/realm/filters:post)}
 

templates/zerver/api/create-user-group.md

@@ -1,4 +1,4 @@
-# Create User Group
+# Create a user group
 
 {generate_api_description(/user_groups/create:post)}
 

templates/zerver/api/delete-queue.md

@@ -1,4 +1,4 @@
-# Delete a queue
+# Delete an event queue
 
 {generate_api_description(/events:delete)}
 

templates/zerver/api/delete-stream.md

@@ -1,4 +1,4 @@
-# Delete stream
+# Delete a stream
 
 {generate_api_description(/streams/{stream_id}:delete)}
 

templates/zerver/api/get-linkifiers.md

@@ -1,4 +1,4 @@
-# List linkifiers
+# Get linkifiers
 
 {generate_api_description(/realm/filters:get)}
 

templates/zerver/api/get-own-user.md

@@ -1,4 +1,4 @@
-# Get profile
+# Get own user
 
 {generate_api_description(/users/me:get)}
 

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

@@ -1,4 +1,4 @@
-# Get a raw message
+# Get a message's raw markdown
 
 {generate_api_description(/messages/{message_id}:get)}
 

templates/zerver/api/get-server-settings.md

@@ -1,4 +1,4 @@
-# Get global settings
+# Get server settings
 
 {generate_api_description(/server_settings:get)}
 

templates/zerver/api/get-subscription-status.md

@@ -1,4 +1,4 @@
-# Get user subscription status
+# Get subscription status
 
 {generate_api_description(/users/{user_id}/subscriptions/{stream_id}:get)}
 

templates/zerver/api/remove-linkifier.md

@@ -1,4 +1,4 @@
-# Remove linkifiers
+# Remove a linkifier
 
 {generate_api_description(/realm/filters/{filter_id}:delete)}
 

templates/zerver/api/subscribe.md

@@ -1,4 +1,4 @@
-# Add subscriptions
+# Subscribe to a stream
 
 {generate_api_description(/users/me/subscriptions:post)}
 

templates/zerver/api/unsubscribe.md

@@ -1,4 +1,4 @@
-# Remove subscriptions
+# Unsubscribe from a stream
 
 {generate_api_description(/users/me/subscriptions:delete)}
 

templates/zerver/api/update-message-flags.md

@@ -1,4 +1,4 @@
-# Update a message's flags
+# Update personal message flags
 
 {generate_api_description(/messages/flags:post)}
 

templates/zerver/api/update-message.md

@@ -1,4 +1,4 @@
-# Update a message
+# Edit a message
 
 {generate_api_description(/messages/{message_id}:patch)}
 

templates/zerver/api/update-stream.md

@@ -1,4 +1,4 @@
-# Update stream
+# Update a stream
 
 {generate_api_description(/streams/{stream_id}:patch)}
 

templates/zerver/api/update-subscription-settings.md

@@ -1,4 +1,4 @@
-# Update subscription properties
+# Update subscription settings
 
 {generate_api_description(/users/me/subscriptions/properties:post)}
 

templates/zerver/api/update-user-group.md

@@ -1,4 +1,4 @@
-# Update User Group
+# Update a user group
 
 {generate_api_description(/user_groups/{group_id}:patch)}
 

templates/zerver/api/update-user.md

@@ -1,4 +1,4 @@
-# Update User
+# Update a user
 
 {!api-admin-only.md!}
 

templates/zerver/api/upload-custom-emoji.md

@@ -1,4 +1,4 @@
-# Upload a custom emoji
+# Upload custom emoji
 
 {generate_api_description(/realm/emoji/{emoji_name}:post)}
 

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

@@ -1,58 +1,58 @@
 #### 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)
+* [Upload a file](/api/upload-file)
+* [Edit a message](/api/update-message)
+* [Delete a message](/api/delete-message)
+* [Get messages](/api/get-messages)
+* [Construct a narrow](/api/construct-narrow)
 * [Add an emoji reaction](/api/add-reaction)
 * [Remove an emoji reaction](/api/remove-reaction)
 * [Render a message](/api/render-message)
-* [Upload a file](/api/upload-file)
+* [Get a message's raw markdown](/api/get-raw-message)
-* [Delete a message](/api/delete-message)
-* [Construct a narrow](/api/construct-narrow)
 * [Get a message's edit history](/api/get-message-history)
-* [Update a message's flags](/api/update-message-flags)
+* [Update personal message flags](/api/update-message-flags)
 * [Mark messages as read in bulk](/api/mark-all-as-read)
 
 #### Streams
 
-* [Get all streams](/api/get-streams)
 * [Get subscribed streams](/api/get-subscriptions)
-* [Add subscriptions](/api/subscribe)
+* [Subscribe to a stream](/api/subscribe)
-* [Update subscription settings](/api/update-subscription-settings)
+* [Unsubscribe from a stream](/api/unsubscribe)
-* [Remove subscriptions](/api/unsubscribe)
 * [Get subscription status](/api/get-subscription-status)
+* [Update subscription settings](/api/update-subscription-settings)
+* [Get all streams](/api/get-streams)
+* [Get stream ID](/api/get-stream-id)
+* [Create a stream](/api/create-stream)
+* [Update a stream](/api/update-stream)
+* [Delete a stream](/api/delete-stream)
 * [Get topics in a stream](/api/get-stream-topics)
 * [Topic muting](/api/mute-topic)
-* [Create a stream](/api/create-stream)
-* [Get stream ID](/api/get-stream-id)
-* [Delete a stream](/api/delete-stream)
-* [Update a stream](/api/update-stream)
 
 #### Users
 
 * [Get all users](/api/get-users)
+* [Get own user](/api/get-own-user)
 * [Get a user](/api/get-user)
+* [Update a user](/api/update-user)
+* [Create a user](/api/create-user)
 * [Deactivate a user](/api/deactivate-user)
 * [Reactivate a user](/api/reactivate-user)
-* [Update a user](/api/update-user)
-* [Get profile](/api/get-own-user)
-* [Create a user](/api/create-user)
 * [Set "typing" status](/api/set-typing-status)
 * [Get user presence](/api/get-user-presence)
-* [Get all user groups](/api/get-user-groups)
+* [Get attachments](/api/get-attachments)
 * [Update notification settings](/api/update-notification-settings)
+* [Get user groups](/api/get-user-groups)
 * [Create a user group](/api/create-user-group)
 * [Update a user group](/api/update-user-group)
 * [Delete a user group](/api/remove-user-group)
-* [Get attachments](/api/get-attachments)
 
 #### Server & organizations
 
 * [Get server settings](/api/get-server-settings)
-* [List linkifiers](/api/get-linkifiers)
+* [Get linkifiers](/api/get-linkifiers)
-* [Create linkifiers](/api/add-linkifier)
+* [Add a linkifier](/api/add-linkifier)
-* [Remove linkifiers](/api/remove-linkifier)
+* [Remove a linkifier](/api/remove-linkifier)
 * [Get all custom emoji](/api/get-custom-emoji)
 * [Upload custom emoji](/api/upload-custom-emoji)
 

zerver/openapi/zulip.yaml

@@ -1191,7 +1191,8 @@ paths:
       operationId: update_message_flags
       tags: ["messages"]
       description: |
-        Add or remove flags in a list of messages.
+        Add or remove personal message flags like `read` and `starred`
+        on a collection of message IDs.
 
         `POST {{ api_url }}/v1/messages/flags`