docs: Improve closing of life-of-a-request.

Reading the previous commit reminded me of various other details we
should document here.
This commit is contained in:
Tim Abbott 2022-02-04 15:24:13 -08:00
parent c2b6e76af7
commit 39dea1feaf
1 changed files with 13 additions and 9 deletions

View File

@ -198,18 +198,22 @@ Our API works on JSON requests and responses. Every API endpoint should
{"result": "error", "msg": "<some error message>", "code": "BAD_REQUEST"}
```
in a
[HTTP response](https://docs.djangoproject.com/en/3.2/ref/request-response/)
with a content type of 'application/json'.
in a [Django HttpResponse
object](https://docs.djangoproject.com/en/3.2/ref/request-response/)
with a `Content-Type` of 'application/json'.
To pass back data from the server to the calling client, in the event of
a successfully handled request, we use `json_success(request, data)`.
The request argument is a
[HTTP request](https://docs.djangoproject.com/en/3.2/ref/request-response/)
with additional metadata that Zulip associates with the request object.
The data argument is a python object which can be converted to a JSON string
and has a default value of an empty python dictionary.
The `request` argument is a [Django HttpRequest
object](https://docs.djangoproject.com/en/3.2/ref/request-response/).
The `data` argument is a Python object which can be converted to a JSON
string and has a default value of an empty Python dictionary.
Zulip stores additional metadata it has associated with that HTTP
request in a `RequestNotes` object, which is primarily accessed in
common code used in all requests (middleware, logging, rate limiting,
etc.).
This will result in a JSON string:
@ -217,6 +221,6 @@ This will result in a JSON string:
{"result": "success", "msg": "", "data": {"var_name1": "var_value1", "var_name2": "var_value2"}}
```
with a HTTP 200 status and a content type of 'application/json'.
with a HTTP 200 status and a `Content-Type` of 'application/json'.
That's it!