reference: media type handlers

docs/how-tos/create-soap-endpoint.rst

@@ -5,22 +5,20 @@ Create a SOAP endpoint
 
 :author: `fjf2002 <https://github.com/fjf2002>`_
 
-PostgREST now has XML support. With a bit of work, SOAP endpoints become possible.
-
-Please note that PostgREST supports just ``text/xml`` MIME type in request/response headers ``Content-Type`` and ``Accept``.
-If you have to use other MIME types such as ``application/soap+xml``, you could manipulate the headers in your reverse proxy.
-
-
+PostgREST supports :ref:`custom_media`. With a bit of work, SOAP endpoints become possible.
 
 Minimal Example
 ---------------
+
 This example will simply return the request body, inside a tag ``therequestbodywas``.
 
 Add the following function to your PostgreSQL database:
 
 .. code-block:: postgres
 
-   CREATE OR REPLACE FUNCTION my_soap_endpoint(xml) RETURNS xml AS $$
+   create domain "text/xml" as pg_catalog.xml;
+
+   CREATE OR REPLACE FUNCTION my_soap_endpoint(xml) RETURNS "text/xml" AS $$
    DECLARE
      nsarray CONSTANT text[][] := ARRAY[
        ARRAY['soapenv', 'http://schemas.xmlsoap.org/soap/envelope/']
@@ -121,7 +119,7 @@ potentially disclosing internals to the client, but instead handle the errors di
        xmlelement(NAME "soapenv:Body", body)
      );
    $function$;
-   
+
    -- helper function
    CREATE OR REPLACE FUNCTION _soap_exception(
      faultcode text,
@@ -137,9 +135,9 @@ potentially disclosing internals to the client, but instead handle the errors di
        )
      );
    $function$;
-   
+
    CREATE OR REPLACE FUNCTION fraction_to_decimal(xml)
-    RETURNS xml
+    RETURNS "text/xml"
     LANGUAGE plpgsql
    AS $function$
    DECLARE
@@ -207,14 +205,14 @@ The output should roughly look like:
      </soapenv:Body>
    </soapenv:Envelope>
 
-
 References
 ----------
+
 For more information concerning PostgREST, cf.
 
 - :ref:`s_proc_single_unnamed`
-- :ref:`scalar_return_formats`
-- :ref:`Nginx reverse proxy <admin>`
+- :ref:`custom_media`. See :ref:`any_handler`, if you need to support an ``application/soap+xml`` media type.
+- :ref:`Nginx reverse proxy <nginx>`
 
 For SOAP reference, visit
 

docs/how-tos/providing-html-content-using-htmx.rst

@@ -23,7 +23,7 @@ To simplify things, we won't be using authentication, so grant all permissions o
   grant all on api.todos to web_anon;
   grant usage, select on sequence api.todos_id_seq to web_anon;
 
-Next, add the ``text/html`` media type as a DOMAIN. With this, PostgREST can identify the request made by your web browser (with the ``Accept: text/html`` header)
+Next, add the ``text/html`` as a :ref:`custom_media`. With this, PostgREST can identify the request made by your web browser (with the ``Accept: text/html`` header)
 and return a raw HTML document file.
 
 .. code-block:: postgres

docs/how-tos/providing-images-for-img.rst

@@ -26,18 +26,42 @@ First, we need a public table for storing the files.
    , blob bytea
    );
 
-Let's assume this table contains an image of two cute kittens with id 42.
-We can retrieve this image in binary format from our PostgREST API by requesting :code:`/files?select=blob&id=eq.42` with the :code:`Accept: application/octet-stream` header.
-Unfortunately, putting the URL into the :code:`src` of an :code:`<img>` tag will not work.
-That's because browsers do not send the required :code:`Accept: application/octet-stream` header.
+Let's assume this table contains an image of two cute kittens with id 42. We can retrieve this image in binary format from our PostgREST API by using :ref:`custom_media`:
+
+.. code-block:: postgres
+
+   create domain "application/octet-stream" as bytea;
+
+   create or replace function file(id int) returns "application/octet-stream" as $$
+     select blob from files where id = file.id;
+   $$ language sql;
+
+Now we can request the RPC endpoint :code:`/rpc/file?id=42` with the :code:`Accept: application/octet-stream` header.
+
+
+.. code-block:: bash
+
+   curl "localhost:3000/rpc/file?id=42" -H "Accept: application/octet-stream"
+
+
+Unfortunately, putting the URL into the :code:`src` of an :code:`<img>` tag will not work. That's because browsers do not send the required :code:`Accept: application/octet-stream` header.
+Instead, the :code:`Accept: image/webp` header is sent by many web browsers by default.
+
+Luckily we can change the accepted media type in the function like so:
+
+.. code-block:: postgres
+
+   create domain "image/webp" as bytea;
+
+   create or replace function file(id int) returns "image/webp" as $$
+     select blob from files where id = file.id;
+   $$ language sql;
 
-Luckily we can specify the accepted media types in the :ref:`raw-media-types` configuration variable.
-In this case, the :code:`Accept: image/webp` header is sent by many web browsers by default, so let's add it to the configuration variable, like this: :code:`raw-media-types="image/webp"`.
 Now, the image will be displayed in the HTML page:
 
 .. code-block:: html
 
-   <img src="http://localhost:3000/files?select=blob&id=eq.42" alt="Cute Kittens"/>
+   <img src="http://localhost:3000/file?id=42" alt="Cute Kittens"/>
 
 Improved Version
 ----------------
@@ -60,13 +84,15 @@ First, in addition to the minimal example, we need to store the media types and
      add column type text,
      add column name text;
 
-Next, we set up an RPC endpoint that sets the content type and filename.
+Next, we set modify the function to set the content type and filename.
 We use this opportunity to configure some basic, client-side caching.
 For production, you probably want to configure additional caches, e.g. on the :ref:`reverse proxy <admin>`.
 
 .. code-block:: postgres
 
-   create function file(id int) returns bytea as
+   create domain "*/*" as bytea;
+
+   create function file(id int) returns "*/*" as
    $$
      declare headers text;
      declare blob bytea;
@@ -79,7 +105,7 @@ For production, you probably want to configure additional caches, e.g. on the :r
        from files where files.id = file.id into headers;
        perform set_config('response.headers', headers, true);
        select files.blob from files where files.id = file.id into blob;
-       if found
+       if FOUND -- special var, see https://www.postgresql.org/docs/current/plpgsql-statements.html#PLPGSQL-STATEMENTS-DIAGNOSTICS
        then return(blob);
        else raise sqlstate 'PT404' using
          message = 'NOT FOUND',

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

@@ -506,33 +506,26 @@ Now, to send the file ``postgrest-logo.png`` we need to set the ``Content-Type:
       -X POST -H "Content-Type: application/octet-stream" \
       --data-binary "@postgrest-logo.png"
 
-To get the image from the database, set the ``Accept: application/octet-stream`` header and select only the
-``bytea`` type column.
+To get the image from the database, use :ref:`custom_media` like so:
 
-.. tabs::
-
-  .. code-tab:: http
-
-    GET /files?select=file&id=eq.1 HTTP/1.1
-    Accept: application/octet-stream
-
-  .. code-tab:: bash Curl
+.. code-block:: postgres
 
-    curl "http://localhost:3000/files?select=file&id=eq.1" \
-      -H "Accept: application/octet-stream"
+  create domain "image/png" as bytea;
 
-Use more accurate headers according to the type of the files by using the :ref:`raw-media-types` configuration. For example, adding the ``raw-media-types="image/png"`` setting to the configuration file will allow you to use the ``Accept: image/png`` header:
+  create or replace get_image(id int) returns "image/png" as $$
+    select file from files where id = $1;
+  $$ language sql;
 
 .. tabs::
 
   .. code-tab:: http
 
-    GET /files?select=file&id=eq.1 HTTP/1.1
+    GET /get_image?id=1 HTTP/1.1
     Accept: image/png
 
   .. code-tab:: bash Curl
 
-    curl "http://localhost:3000/files?select=file&id=eq.1" \
+    curl "http://localhost:3000/get_image?id=1" \
       -H "Accept: image/png"
 
 See :ref:`providing_img` for a step-by-step example on how to handle images in HTML.

docs/references/api.rst

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