From 6e24e23b4b99ed1232aa82869933e0211428db20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franz-Josef=20F=C3=A4rber?= Date: Thu, 28 Apr 2022 10:31:32 +0200 Subject: [PATCH] Allow returning XML --- docs/api.rst | 84 +++++++++++++++++++--------------------- docs/configuration.rst | 6 +-- docs/errors.rst | 5 ++- docs/releases/v6.0.2.rst | 2 +- 4 files changed, 46 insertions(+), 51 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 2eb7e7cd9..3f95f1dca 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -801,7 +801,13 @@ The current possibilities are: * ``text/csv`` * ``application/json`` * ``application/openapi+json`` + +and in the special case of a single-column select the following additional three formats; +also see the section :ref:`scalar_return_formats`: + * ``application/octet-stream`` +* ``text/plain`` +* ``text/xml`` The server will default to JSON for API endpoints and OpenAPI on the root. @@ -2216,6 +2222,9 @@ PostgREST will detect if the function is scalar or table-valued and will shape t { "title": "Blade Runner 2049", "rating": 8.1} ] +To manually choose a return format such as binary, plain text or XML, see the section :ref:`scalar_return_formats`. + + .. _bulk_call: Bulk Call @@ -2319,12 +2328,25 @@ You can call overloaded functions with different number of arguments. Overloaded functions with the same argument names but different types are not supported. -.. _binary_output: +.. _scalar_return_formats: -Binary Output -============= +Response Formats For Scalar Responses +===================================== -If you want to return raw binary data from a :code:`bytea` column, you must specify :code:`application/octet-stream` as part of the :code:`Accept` header +For scalar return values such as + +* single-column selects on tables or +* scalar functions, + +you can set the additional content types + +* ``application/octet-stream`` +* ``text/plain`` +* ``text/xml`` + +as part of the :code:`Accept` header. + +Example 1: If you want to return raw binary data from a :code:`bytea` column, you must specify :code:`application/octet-stream` as part of the :code:`Accept` header and select a single column :code:`?select=bin_data`. .. tabs:: @@ -2339,74 +2361,46 @@ and select a single column :code:`?select=bin_data`. curl "http://localhost:3000/items?select=bin_data&id=eq.1" \ -H "Accept: application/octet-stream" -You can also request binary output when calling `Stored Procedures`_ and since they can return a scalar value you are not forced to use :code:`select` -for this case. +Example 2: You can request XML output when calling `Stored Procedures`_ that return a scalar value of type ``text/xml``. You are not forced to use select for this case. .. code-block:: postgres - CREATE FUNCTION closest_point(..) RETURNS bytea .. + CREATE FUNCTION generate_xml_content(..) RETURNS xml .. .. tabs:: .. code-tab:: http - POST /rpc/closest_point HTTP/1.1 - Accept: application/octet-stream + POST /rpc/generate_xml_content HTTP/1.1 + Accept: text/xml .. code-tab:: bash Curl - curl "http://localhost:3000/rpc/closest_point" \ - -X POST -H "Accept: application/octet-stream" + curl "http://localhost:3000/rpc/generate_xml_content" \ + -X POST -H "Accept: text/xml" -If the stored procedure returns non-scalar values, you need to do a :code:`select` in the same way as for GET binary output. +Example 3: If the stored procedure returns non-scalar values, you need to do a :code:`select` in the same way as for GET binary output. .. code-block:: sql - CREATE FUNCTION overlapping_regions(..) RETURNS SETOF TABLE(geom_twkb bytea, ..) .. + CREATE FUNCTION get_descriptions(..) RETURNS SETOF TABLE(id int, description text) .. .. tabs:: .. code-tab:: http - POST /rpc/overlapping_regions?select=geom_twkb HTTP/1.1 - Accept: application/octet-stream - - .. code-tab:: bash Curl - - curl "http://localhost:3000/rpc/overlapping_regions?select=geom_twkb" \ - -X POST -H "Accept: application/octet-stream" - -.. note:: - - If more than one row would be returned the binary results will be concatenated with no delimiter. - -.. _plain_text_output: - -Plain Text Output ------------------ - -You can get raw output from a ``text`` column by using ``Accept: text/plain``. - -.. tabs:: - - .. code-tab:: http - - GET /workers?select=custom_psv_format HTTP/1.1 + POST /rpc/get_descriptions?select=description HTTP/1.1 Accept: text/plain .. code-tab:: bash Curl - curl "http://localhost:3000/workers?select=custom_psv_format" \ - -H "Accept: text/plain" + curl "http://localhost:3000/rpc/get_descriptions?select=description" \ + -X POST -H "Accept: text/plain" -.. code-block:: text +.. note:: - 09310817|JOHN|DOE|15/04/88| - 42152780|FRED|BLOGGS|20/02/85| - 43006541|OTTO|NORMALVERBRAUCHER|01/07/90| - 02452492|ERIKA|MUSTERMANN|11/01/80| + If more than one row would be returned the binary/plain-text/xml results will be concatenated with no delimiter. -This follows the same rules as :ref:`binary_output`. .. _open-api: diff --git a/docs/configuration.rst b/docs/configuration.rst index 57c22199b..9d2a33619 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -587,14 +587,14 @@ raw-media-types This serves to extend the `Media Types `_ that PostgREST currently accepts through an ``Accept`` header. - These media types can be requested by following the same rules as the ones defined in :ref:`binary_output`. + These media types can be requested by following the same rules as the ones defined in :ref:`scalar_return_formats`. As an example, the below config would allow you to request an **image** and a **XML** file by doing a request with ``Accept: image/png`` - or ``Accept: text/xml``, respectively. + or ``Accept: font/woff2``, respectively. .. code:: bash - raw-media-types="image/png, text/xml" + raw-media-types="image/png, font/woff2" .. _server-host: diff --git a/docs/errors.rst b/docs/errors.rst index 248051f98..08782f4ec 100644 --- a/docs/errors.rst +++ b/docs/errors.rst @@ -193,8 +193,9 @@ Related to the HTTP request elements. | | See :ref:`guc_resp_status`. | | PGRST112 | | +---------------+-------------------------------------------------------------+ -| .. _pgrst113: | Related to :ref:`binary_output`. See :ref:`providing_img` | -| | for an example on requesting images. | +| .. _pgrst113: | Related to :ref:`scalar_return_formats`. | +| | See :ref:`providing_img` for an example on requesting | +| | images. | | PGRST113 | | +---------------+-------------------------------------------------------------+ | .. _pgrst114: | For an :ref:`UPSERT using PUT `, when | diff --git a/docs/releases/v6.0.2.rst b/docs/releases/v6.0.2.rst index 88a73ee5c..f96550515 100644 --- a/docs/releases/v6.0.2.rst +++ b/docs/releases/v6.0.2.rst @@ -23,7 +23,7 @@ Added * Bulk calling an RPC is now allowed. See :ref:`bulk_call`. |br| -- `@steve-chavez `_ -* It's now possible to request a ``text/plain`` output. See :ref:`plain_text_output`. +* It's now possible to request a ``text/plain`` output. See :ref:`scalar_return_formats`. |br| -- `@steve-chavez `_ * Config option for specifying PostgREST database pool timeout. See :ref:`db-pool-timeout`.