Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

api-docs: Clarify the behavior of the near operator. 

On the server-side, the implementation of the "near" operator is a
noop. Clients should instead use the "anchor" parameter to express
the "near" operator in a search box or URL fragment.
This commit is contained in:
Lauryn Menard 2024-08-19 17:16:42 +02:00 committed by Tim Abbott
parent d9f25d01a1
commit 3cb14ba7db
1 changed files with 21 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
api_docs/construct-narrow.md
View File

@ -95,9 +95,16 @@ messages](/api/update-message-flags-for-narrow)).
### Message IDs ### Message IDs
The `near`, `id` and `with` operators use message IDs for their The `id` and `with` operators use message IDs for their operands. The
operands. The `near` and `id` operators are documented in the help message ID operand for these two operators may be encoded as either a
center [here](/help/search-for-messages#search-by-message-id). number or a string.
* `id:12345`: Search for only the message with ID `12345`.
* `with:12345`: Search for the conversation that contains the message
with ID `12345`.
The `id` operator returns the message with the specified ID if it exists,
and if it can be accessed by the user.
The `with` operator is designed to be used for permanent links to topics, The `with` operator is designed to be used for permanent links to topics,
which means they should continue to work when the topic is which means they should continue to work when the topic is
@ -108,14 +115,15 @@ with the `channel`/`topic`/`dm` operators corresponding to the current
conversation containing that message, and replacing any such filters conversation containing that message, and replacing any such filters
included in the narrow. included in the narrow.
* `with:12345`: Search for the conversation that contains the message The [help center](/help/search-for-messages#search-by-message-id) also
with ID `12345`. documents the `near` operator for searching for messages by ID, but
* `near:12345`: Search messages around the message with ID `12345`. this narrow operator has no effect on filtering messages when sent to
* `id:12345`: Search for only the message with ID `12345`. the server. In practice, when the `near` operator is used to search for
messages, or is part of a URL fragment, the value of its operand should
The message ID operand for the `with` and `id` operators may be encoded instead be used for the value of the `anchor` parameter in endpoints
as either a number or a string. The message ID operand for the `near` that also accept a `narrow` parameter; see
operator must be encoded as a string. [GET /messages][anchor-get-messages] and
[POST /messages/flags/narrow][anchor-post-flags].
**Changes**: Prior to Zulip 8.0 (feature level 194), the message ID **Changes**: Prior to Zulip 8.0 (feature level 194), the message ID
operand for the `id` operator needed to be encoded as a string. operand for the `id` operator needed to be encoded as a string.
@ -171,3 +179,5 @@ user 1234, and user 5678, the correct JSON-encoded query is:
[view-profile]: /help/view-someones-profile [view-profile]: /help/view-someones-profile
[browse-channels]: /help/introduction-to-channels#browse-and-subscribe-to-channels [browse-channels]: /help/introduction-to-channels#browse-and-subscribe-to-channels
[anchor-get-messages]: /api/get-messages#parameter-anchor
[anchor-post-flags]: /api/update-message-flags-for-narrow#parameter-anchor