mirror of
https://github.com/zulip/zulip.git
synced 2025-10-24 08:33:43 +00:00
docs: Apply bullet style changes from Prettier.
Signed-off-by: Anders Kaseorg <anders@zulip.com>
(cherry picked from commit 915884bff7)
This commit is contained in:
committed by
Tim Abbott
parent
5ae8fe292d
commit
0147c6adce
@@ -89,15 +89,15 @@ With the exception of incoming webhooks (which we do not usually control the
|
||||
format of), legacy endpoints, and logged-out endpoints, Zulip uses REST
|
||||
for its API. This means that we use:
|
||||
|
||||
* POST for creating something new where we don't have a unique
|
||||
- POST for creating something new where we don't have a unique
|
||||
ID. Also used as a catch-all if no other verb is appropriate.
|
||||
* PUT for creating something for which we have a unique ID.
|
||||
* DELETE for deleting something
|
||||
* PATCH for updating or editing attributes of something.
|
||||
* GET to get something (read-only)
|
||||
* HEAD to check the existence of something to GET, without getting it;
|
||||
- PUT for creating something for which we have a unique ID.
|
||||
- DELETE for deleting something
|
||||
- PATCH for updating or editing attributes of something.
|
||||
- GET to get something (read-only)
|
||||
- HEAD to check the existence of something to GET, without getting it;
|
||||
useful to check a link without downloading a potentially large link
|
||||
* OPTIONS (handled automatically, see more below)
|
||||
- OPTIONS (handled automatically, see more below)
|
||||
|
||||
Of these, PUT, DELETE, HEAD, OPTIONS, and GET are *idempotent*, which
|
||||
means that we can send the request multiple times and get the same
|
||||
|
||||
@@ -202,9 +202,9 @@ dictionary.
|
||||
`property_types`.** However, there are some properties that need custom
|
||||
logic and thus cannot use this framework. For example:
|
||||
|
||||
* The realm `authentication_methods` attribute is a bitfield and needs
|
||||
- The realm `authentication_methods` attribute is a bitfield and needs
|
||||
additional code for validation and updating.
|
||||
* The `allow_message_editing` and `message_content_edit_limit_seconds`
|
||||
- The `allow_message_editing` and `message_content_edit_limit_seconds`
|
||||
fields depend on one another, so they are also handled separately and
|
||||
not included in `property_types`.
|
||||
|
||||
|
||||
@@ -129,11 +129,11 @@ view, you need to write code to parse and validate that the arguments
|
||||
exist and have the correct form. For many applications, this leads to
|
||||
one of several bad outcomes:
|
||||
|
||||
* The code isn't written, so arguments aren't validated, leading to
|
||||
- The code isn't written, so arguments aren't validated, leading to
|
||||
bugs and confusing error messages for users of the API.
|
||||
* Every function starts with a long list of semi-redundant validation
|
||||
- Every function starts with a long list of semi-redundant validation
|
||||
code, usually with highly inconsistent error messages.
|
||||
* Every view function comes with another function that does the
|
||||
- Every view function comes with another function that does the
|
||||
validation that has the problems from the last bullet point.
|
||||
|
||||
In Zulip, we solve this problem with a the special decorator called
|
||||
@@ -178,22 +178,22 @@ in
|
||||
|
||||
REQ also helps us with request variable validation. For example:
|
||||
|
||||
* `msg_ids = REQ(json_validator=check_list(check_int))` will check
|
||||
- `msg_ids = REQ(json_validator=check_list(check_int))` will check
|
||||
that the `msg_ids` HTTP parameter is a list of integers, marshalled
|
||||
as JSON, and pass it into the function as the `msg_ids` Python
|
||||
keyword argument.
|
||||
|
||||
* `streams_raw = REQ("subscriptions", json_validator=check_list(check_string))`
|
||||
- `streams_raw = REQ("subscriptions", json_validator=check_list(check_string))`
|
||||
will check that the "subscriptions" HTTP parameter is a list of
|
||||
strings, marshalled as JSON, and pass it into the function with the
|
||||
Python keyword argument `streams_raw`.
|
||||
|
||||
* `message_id=REQ(converter=to_non_negative_int)` will check that the
|
||||
- `message_id=REQ(converter=to_non_negative_int)` will check that the
|
||||
`message_id` HTTP parameter is a string containing a non-negative
|
||||
integer (`converter` differs from `json_validator` in that it does
|
||||
not automatically marshall the input from JSON).
|
||||
|
||||
* Since there is no need to JSON-encode strings, usually simply
|
||||
- Since there is no need to JSON-encode strings, usually simply
|
||||
`my_string=REQ()` is correct. One can pass e.g.
|
||||
`str_validator=check_string_in(...)` where one wants to run a
|
||||
validator on the value of a string.
|
||||
|
||||
Reference in New Issue
Block a user