add documentation for handling preference (#684)

docs/references/api.rst

@@ -17,6 +17,7 @@ PostgREST exposes three database objects of a schema as resources: tables, views
    api/resource_embedding.rst
    api/resource_representation.rst
    api/openapi.rst
+   api/preferences.rst
    api/*
 
 .. raw:: html

docs/references/api/preferences.rst

@@ -0,0 +1,47 @@
+.. _preferences:
+
+Preferences
+###########
+
+PostgREST honors the Prefer HTTP header specified on `RFC 7240 <https://www.rfc-editor.org/rfc/rfc7240.html>`_. It allows clients to specify required and optional behaviors for their requests.
+
+.. _prefer_handling:
+
+Strict or Lenient Handling
+==========================
+
+The server ignores unrecognized or unfulfillable preferences by default. You can control this behavior with the ``handling`` preference. It can take two values: ``lenient`` (the default) or ``strict``.
+
+``handling=strict`` will throw an error if you specify invalid preferences. For instance:
+
+.. code-block:: http
+
+  GET /projects HTTP/1.1
+  Prefer: handling=strict, foo, bar
+
+.. code-block:: http
+
+  HTTP/1.1 400 Bad Request
+  Content-Type: application/json; charset=utf-8
+
+.. code-block:: json
+
+  {
+      "code": "PGRST122",
+      "message": "Invalid preferences given with handling=strict",
+      "details": "Invalid preferences: foo, bar",
+      "hint": null
+  }
+
+
+``handling=lenient`` ignores invalid preferences.
+
+.. code-block:: http
+
+  GET /projects HTTP/1.1
+  Prefer: handling=lenient, foo, bar
+
+.. code-block:: http
+
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=utf-8

docs/references/errors.rst

@@ -253,6 +253,10 @@ Related to the HTTP request elements.
 |               |             | ``PGRST`` error. See :ref:`raise headers <raise_headers>`.  |
 | PGRST121      |             |                                                             |
 +---------------+-------------+-------------------------------------------------------------+
+| .. _pgrst122: | 400         | Invalid preferences found in ``Prefer`` header with         |
+|               |             | ``Prefer: handling=strict``. See :ref:`prefer_handling`.    |
+| PGRST122      |             |                                                             |
++---------------+-------------+-------------------------------------------------------------+
 
 .. _pgrst2**:
 

postgrest.dict

@@ -185,6 +185,7 @@ unicode
 unikernel
 unix
 updatable
+unfulfillable
 Untyped
 UPSERT
 Upsert