add documentation for timezone preference (#698)

docs/how-tos/working-with-postgresql-data-types.rst

@@ -62,7 +62,7 @@ Someone located in Cairo can retrieve the data using their local time, too:
     }
   ]
 
-The response has the date in the time zone configured by the server: ``UTC -05:00``.
+The response has the date in the time zone configured by the server: ``UTC -05:00`` (see :ref:`prefer_timezone`).
 
 You can use other comparative filters and also all the `PostgreSQL special date/time input values <https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-TABLE>`_ as illustrated in this example:
 

docs/references/api/preferences.rst

@@ -45,3 +45,63 @@ The server ignores unrecognized or unfulfillable preferences by default. You can
 
   HTTP/1.1 200 OK
   Content-Type: application/json; charset=utf-8
+
+.. _prefer_timezone:
+
+Timezone
+========
+
+The ``timezone`` preference allows you to change the `PostgreSQL timezone <https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-TIMEZONE>`_. It accepts all timezones in `pg_timezone_names <https://www.postgresql.org/docs/current/view-pg-timezone-names.html>`_.
+
+
+.. code-block:: http
+
+  GET /timestamps HTTP/1.1
+  Prefer: timezone=America/Los_Angeles
+
+.. code-block:: http
+
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=utf-8
+  Preference-Applied: timezone=America/Los_Angeles
+
+.. code-block:: json
+  
+  [
+    {"t":"2023-10-18T05:37:59.611-07:00"},
+    {"t":"2023-10-18T07:37:59.611-07:00"},
+    {"t":"2023-10-18T09:37:59.611-07:00"}
+  ]
+
+For an invalid timezone, PostgREST returns values with the default timezone (configured on ``postgresql.conf`` or as a setting on the :ref:`authenticator <roles>`).
+
+.. code-block:: http
+
+  GET /timestamps HTTP/1.1
+  Prefer: timezone=Jupiter/Red_Spot
+
+.. code-block:: http
+
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=utf-8
+
+.. code-block:: json
+  
+  [
+    {"t":"2023-10-18T12:37:59.611+00:00"},
+    {"t":"2023-10-18T14:37:59.611+00:00"},
+    {"t":"2023-10-18T16:37:59.611+00:00"}
+  ]
+
+Note that there's no ``Preference-Applied`` in the response.
+
+However, with ``handling=strict``, an invalid timezone preference will throw an :ref:`error <pgrst122>`.
+
+.. code-block:: http
+
+  GET /timestamps HTTP/1.1
+  Prefer: handling=strict, timezone=Jupiter/Red_Spot
+  
+.. code-block:: http
+
+  HTTP/1.1 400 Bad Request