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

api-changelog: Update and clarify docs for feature level 176 entry. 

Revises API changelog entry for missing endpoint method and to
clarify the overall text.

Updates Changes notes for feature level 176 to not have repetitive
text, so that the updates were clearer and more concise.

The original commit with the changes related to this API changelog
entry is commit 268f858f39.
This commit is contained in:
Lauryn Menard 2023-05-19 18:04:36 +02:00 committed by Tim Abbott
parent 4c4caa7be4
commit 03a2c2da6a
2 changed files with 74 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
api_docs/changelog.md
View File

@ -80,18 +80,22 @@ format used by the Zulip server that they are interacting with.
**Feature level 176** **Feature level 176**
* [`POST /realm/filters`](/api/add-linkifier), [`realm/filters/<int:filter_id>`](/api/update-linkifier): * [`POST /realm/filters`](/api/add-linkifier),
The parameter `url_format_string` is replaced by `url_template`. [`PATCH realm/filters/<int:filter_id>`](/api/update-linkifier):
The linkifiers now accept only [RFC 6570][rfc6570] compliant URL Templates. The `url_format_string` parameter is replaced by `url_template`.
The old URL format strings are no longer supported. [Linkifiers](/help/add-a-custom-linkifier) now only accept
[RFC 6570][rfc6570] compliant URL templates. The old URL format
strings are no longer supported.
* [`GET /events`](/api/get-events), [`POST /register`](/api/register-queue): * [`GET /events`](/api/get-events), [`POST /register`](/api/register-queue):
The key `url_format_string` is replaced by `url_template` for the `realm_linkifiers` The `url_format_string` key in `realm_linkifiers` objects is replaced
event type. For backwards-compatibility, clients that do not support the by `url_template`. For backwards-compatibility, clients that do not
`linkifier_url_template` support the `linkifier_url_template`
[client capability](/api/register-queue#parameter-client_capabilities) [client capability](/api/register-queue#parameter-client_capabilities)
will get an empty list in the response of `/register` and not receive `realm_linkifiers` will receive an empty `realm_linkifiers` array in the `/register`
events. Unconditionally, the deprecated event type `realm_filters` gives an empty list in the response and not receive `realm_linkifiers` events. Unconditionally,
response of `/register` and is no longer sent the clients otherwise. the deprecated `realm_filters` event type returns an empty array in
the `/register` response and these events are no longer sent to
clients.
**Feature level 175** **Feature level 175**

128
zerver/openapi/zulip.yaml
View File

@ -3107,26 +3107,19 @@ paths:
set of configured [linkifiers](/help/add-a-custom-linkifier) set of configured [linkifiers](/help/add-a-custom-linkifier)
for the organization has changed. for the organization has changed.
Processing this event is important to doing Markdown local echo Processing this event is important for doing Markdown local echo
correctly. correctly.
The client will not receive this event unless the event queue **Changes**: As of Zulip 7.0 (feature level 176), clients will not
is registered with `linkifier_url_template` client capability set to `true`. receive this event unless the event queue is registered with the
client capability `{"linkifier_url_template": true}`. This is because
the change to specify linkifiers with a URL template instead of a
URL format string is not backwards-compatible.
See [`POST /register`](/api/register-queue#parameter-client_capabilities) See [`POST /register`](/api/register-queue#parameter-client_capabilities)
for how client capabilities can be specified. for how client capabilities can be specified.
**Changes**: Changed in Zulip 7.0 (feature level 176). This event no longer New in Zulip 4.0 (feature level 54), replacing the deprecated
gets sent unless the `linkifier_url_template` client capability is set to `realm_filters` event type.
`true`, due to the backwards-incompatible change from specifying the
URL from a `url_format` format string to `url_template`.
**Changes**: New in Zulip 4.0 (feature level 54), replacing the
previous `realm_filters` event type, which is still sent for
backwards compatibility reasons.
Clients should migrate to requesting and processing the
`realm_linkifiers` event type when possible, since we plan to remove
the legacy `realm_filters` logic entirely in a future release.
properties: properties:
id: id:
$ref: "#/components/schemas/EventIdSchema" $ref: "#/components/schemas/EventIdSchema"
@ -3147,8 +3140,8 @@ paths:
pattern: pattern:
type: string type: string
description: | description: |
The string regex pattern which represents the pattern that The [Python regular expression](https://docs.python.org/3/howto/regex.html)
should be linkified by this linkifier. that represents the pattern that should be linkified by this linkifier.
url_template: url_template:
type: string type: string
description: | description: |
@ -3178,16 +3171,15 @@ paths:
additionalProperties: false additionalProperties: false
deprecated: true deprecated: true
description: | description: |
Legacy event type. Sent to all users in a Zulip organization Legacy event type. Previously, sent to all users in a Zulip organization
when the set of configured [linkifiers](/help/add-a-custom-linkifier) when the set of configured [linkifiers](/help/add-a-custom-linkifier)
for the organization has changed. for the organization has changed.
**Changes**: In Zulip 7.0 (feature level 176), clients will no longer **Changes**: As of Zulip 7.0 (feature level 176), clients will no longer
receive this event. receive this event.
**Changes**: Deprecated in Zulip 4.0 (feature level 54), replaced by **Deprecated** in Zulip 4.0 (feature level 54), and replaced by the
the `realm_linkifiers` event type, which has a clearer name and format, `realm_linkifiers` event type, which has a clearer name and format.
instead.
properties: properties:
id: id:
$ref: "#/components/schemas/EventIdSchema" $ref: "#/components/schemas/EventIdSchema"
@ -3205,12 +3197,12 @@ paths:
- type: integer - type: integer
- type: string - type: string
description: | description: |
An array of tuples, where each tuple describes a linkifier. An array of tuples, where each tuple described a linkifier.
The first element of the tuple is a The first element of the tuple was a string regex pattern which
string regex pattern which represents the pattern that should represented the pattern to be linkified on matching. The second
be linkified on matching. The second element is the URL with which the element was the URL with which the pattern matching string
pattern matching string should be linkified with and the third element should be linkified with, and the third element was the ID of
is the ID of the realm filter. the realm filter.
example: example:
{ {
"type": "realm_filters", "type": "realm_filters",
@ -10606,14 +10598,19 @@ paths:
`/register` response or the presence/absence of a `user_settings` key to `/register` response or the presence/absence of a `user_settings` key to
determine where to look for the data. determine where to look for the data.
- `linkifier_url_template`: Boolean for whether the client accepts linkifiers - `linkifier_url_template`: Boolean for whether the client accepts
that uses [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL [linkifiers][help-linkifiers] that use [RFC 6570][rfc6570] compliant
template for linkifying matches. If false or unset, then the `realm_linkifiers` URL templates for linkifying matches. If false or unset, then the
list in the `/register` response will be empty if present, and no `realm_linkifiers` `realm_linkifiers` array in the `/register` response will be empty
events will be sent. if present, and no `realm_linkifiers` [events][events-linkifiers]
will be sent to the client.
<br />
**Changes**: New in Zulip 7.0 (feature level 176). This capability
is for backwards-compatibility.
**Changes**: New in Zulip 7.0 (feature level 176). This capability is for [help-linkifiers]: /help/add-a-custom-linkifier
backwards-compatibility. [rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html
[events-linkifiers]: /api/get-events#realm_linkifiers
content: content:
application/json: application/json:
schema: schema:
@ -10986,19 +10983,16 @@ paths:
Array of objects where each object describes a single Array of objects where each object describes a single
[linkifier](/help/add-a-custom-linkifier). [linkifier](/help/add-a-custom-linkifier).
If the client capability `linkifier_url_template` is false or unset, then **Changes**: As of Zulip 7.0 (feature level 176), clients will
the `realm_linkifiers` list in the `/register` response will be empty if receive an empty array unless the event queue is registered with the
present, and no `realm_linkifiers` events will be sent. client capability `{"linkifier_url_template": true}`. This is because
See [`POST /register`](/api/register-queue#parameter-client_capabilities). the change to specify linkifiers with a URL template instead of a
for how client capabilities can be specified. URL format string is not backwards-compatible.
See [`client_capabilities`](/api/register-queue#parameter-client_capabilities)
parameter for how this can be specified.
**Changes**: In Zulip 7.0 (feature level 176), clients will always receive New in Zulip 4.0 (feature level 54). Clients can access this data for
an empty list in the response unless they set the `linkifier_url_template` servers on earlier feature levels via the legacy `realm_filters` property.
client capability to `true`.
**Changes**: New in Zulip 4.0 (feature level 54). Clients can
access these data on older server versions via the previous
`realm_filters` key.
items: items:
type: object type: object
additionalProperties: false additionalProperties: false
@ -11006,8 +11000,8 @@ paths:
pattern: pattern:
type: string type: string
description: | description: |
The string regex pattern which represents the pattern that The [Python regular expression](https://docs.python.org/3/howto/regex.html)
should be linkified on matching. pattern which represents the pattern that should be linkified on matching.
url_template: url_template:
type: string type: string
description: | description: |
@ -11030,22 +11024,21 @@ paths:
- type: integer - type: integer
- type: string - type: string
description: | description: |
Legacy property for linkifiers. Present if `realm_filters` is Legacy property for [linkifiers](/help/add-a-custom-linkifier).
present in `fetch_event_types`. Present if `realm_filters` is present in `fetch_event_types`.
When present, this is always an empty array. When present, this is always an empty array.
**Changes**: Became empty in Zulip 7.0 (feature level 176). In previous versions, **Changes**: Prior to Zulip 7.0 (feature level 176), this was an
there is an array of tuples (fixed-length arrays) where each tuple describes array of tuples (fixed-length arrays), where each tuple described
a single [linkifier](/help/add-a-custom-linkifier). a single linkifier. The first element of the tuple was a string
The first element of the tuple is a string regex pattern which represents regex pattern which represented the pattern to be linkified on
the pattern that should be linkified on matching. matching. The second element was the URL with which the pattern
The second element is the URL with which the matching string should be linkified with, and the third element
pattern matching string should be linkified with and the third element was the ID of the realm filter.
is the ID of the realm filter.
**Changes**: Deprecated in Zulip 4.0 (feature level 54), replaced by **Deprecated** in Zulip 4.0 (feature level 54), replaced by the
the `realm_linkifiers` key instead. `realm_linkifiers` key.
realm_playgrounds: realm_playgrounds:
type: array type: array
items: items:
@ -18672,15 +18665,14 @@ components:
name: url_template name: url_template
in: query in: query
description: | description: |
The [RFC The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL template compliant URL template used for the link.
used for the link. If you used named groups for the `pattern`, If you used named groups in `pattern`, you can insert their
you can insert their content here with content here with `{name_of_group}`.
`{name_of_the_capturing_group}`.
**Changes**: New in Zulip 7.0 (feature level 176). This replaced **Changes**: New in Zulip 7.0 (feature level 176). This replaced
the parameter `url_format_string`, which was a format string in which the `url_format_string` parameter, which was a format string in which
named groups' content could be inserted with `%(name_of_the_capturing_group)s`. named groups' content could be inserted with `%(name_of_group)s`.
schema: schema:
type: string type: string
example: https://github.com/zulip/zulip/issues/{id} example: https://github.com/zulip/zulip/issues/{id}