split the API reference

docs/references/api/schemas.rst

@@ -0,0 +1,107 @@
+.. _schemas:
+
+Schemas
+=======
+
+PostgREST can expose a single or multiple schema's tables, views and functions. The :ref:`active database role <roles>` must have the usage privilege on the schemas to access them.
+
+Single schema
+-------------
+
+To expose a single schema, specify a single value in :ref:`db-schemas`.
+
+.. code:: bash
+
+   db-schemas = "api"
+
+This schema is added to the `search_path <https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request using :ref:`tx_settings`.
+
+.. _multiple-schemas:
+
+Multiple schemas
+----------------
+
+To expose multiple schemas, specify a comma-separated list on :ref:`db-schemas`:
+
+.. code:: bash
+
+   db-schemas = "tenant1, tenant2"
+
+To switch schemas, use the ``Accept-Profile`` and ``Content-Profile`` headers.
+
+If you don't specify a Profile header, the first schema in the list(``tenant1`` here) is selected as the default schema.
+
+Only the selected schema gets added to the `search_path <https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH>`_ of every request.
+
+.. note::
+
+   These headers are based on the "Content Negotiation by Profile" spec: https://www.w3.org/TR/dx-prof-conneg
+
+GET/HEAD
+~~~~~~~~
+
+For GET or HEAD, select the schema with ``Accept-Profile``.
+
+.. tabs::
+
+  .. code-tab:: http
+
+     GET /items HTTP/1.1
+     Accept-Profile: tenant2
+
+  .. code-tab:: bash Curl
+
+     curl "http://localhost:3000/items" \
+       -H "Accept-Profile: tenant2"
+
+Other methods
+~~~~~~~~~~~~~
+
+For POST, PATCH, PUT and DELETE, select the schema with ``Content-Profile``.
+
+.. tabs::
+
+  .. code-tab:: http
+
+     POST /items HTTP/1.1
+     Content-Profile: tenant2
+
+     {...}
+
+  .. code-tab:: bash Curl
+
+     curl "http://localhost:3000/items" \
+       -X POST -H "Content-Type: application/json" \
+       -H "Content-Profile: tenant2" \
+       -d '{...}'
+
+You can also select the schema for :ref:`s_procs` and :ref:`open-api`.
+
+Restricted schemas
+~~~~~~~~~~~~~~~~~~
+
+You can only switch to a schema included in :ref:`db-schemas`. Using another schema will result in an error:
+
+.. tabs::
+
+  .. code-tab:: http
+
+     GET /items HTTP/1.1
+     Accept-Profile: tenant3
+
+     {...}
+
+  .. code-tab:: bash Curl
+
+     curl "http://localhost:3000/items" \
+       -H "Accept-Profile: tenant3"
+
+.. code-block::
+
+  {
+    "code":"PGRST106",
+    "details":null,
+    "hint":null,
+    "message":"The schema must be one of the following: tenant1, tenant2"
+  }
+