From 5ba370fe0a292e357bb4dd7a8e16091de710245b Mon Sep 17 00:00:00 2001
From: Taimoor Zaeem <mtaimoorzaeem@gmail.com>
Date: Sat, 7 Oct 2023 08:23:41 +0500
Subject: [PATCH] add documentation for handling preference (#684)

---
 docs/references/api.rst             |  1 +
 docs/references/api/preferences.rst | 47 +++++++++++++++++++++++++++++
 docs/references/errors.rst          |  4 +++
 postgrest.dict                      |  1 +
 4 files changed, 53 insertions(+)
 create mode 100644 docs/references/api/preferences.rst

diff --git a/docs/references/api.rst b/docs/references/api.rst
index 0796ba1af..7d817159f 100644
--- a/docs/references/api.rst
+++ b/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
diff --git a/docs/references/api/preferences.rst b/docs/references/api/preferences.rst
new file mode 100644
index 000000000..e151e2b08
--- /dev/null
+++ b/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
diff --git a/docs/references/errors.rst b/docs/references/errors.rst
index 3b1220412..718881d24 100644
--- a/docs/references/errors.rst
+++ b/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**:
 
diff --git a/postgrest.dict b/postgrest.dict
index 30a919d01..15a732531 100644
--- a/postgrest.dict
+++ b/postgrest.dict
@@ -185,6 +185,7 @@ unicode
 unikernel
 unix
 updatable
+unfulfillable
 Untyped
 UPSERT
 Upsert