From f188c15557c2ef9f2ce902f900dc2b03a2b7ff2f Mon Sep 17 00:00:00 2001 From: SteveBash Date: Wed, 22 Mar 2017 12:29:00 -0500 Subject: [PATCH 1/3] Fix typo --- api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api.rst b/api.rst index edf2b8f4f..5bc41df41 100644 --- a/api.rst +++ b/api.rst @@ -350,7 +350,7 @@ Every stored procedure in the API-exposed database schema is accessible under th POST /rpc/function_name HTTP/1.1 -Procedures must used `named arguments `_. To supply arguments in an API call, include a JSON object in the request payload and each key/value of the object will become an argument. +Procedures must be used with `named arguments `_. To supply arguments in an API call, include a JSON object in the request payload and each key/value of the object will become an argument. For instance, assume we have created this function in the database. From d773dd09638c0d237cf375c9e0745c12e6b30a7a Mon Sep 17 00:00:00 2001 From: SteveBash Date: Thu, 23 Mar 2017 11:11:42 -0500 Subject: [PATCH 2/3] Reorder of OpenAPI --- api.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/api.rst b/api.rst index 5bc41df41..c3c1c3c7c 100644 --- a/api.rst +++ b/api.rst @@ -243,17 +243,6 @@ This returns Admittedly PostgREST could detect when there is an equality condition holding on all columns constituting the primary key and automatically convert to singular. However this could lead to a surprising change of format that breaks unwary client code just by filtering on an extra column. Instead we allow manually specifying singular vs plural to decouple that choice from the URL format. -OpenAPI Support -=============== - -Every API hosted by PostgREST automatically serves a full `OpenAPI `_ description on the root path. This provides a list of all endpoints, along with supported HTTP verbs and example payloads. - -You can use a tool like `Swagger UI `_ to create beautiful documentation from the description and to host an interactive web-based dahsboard. The dashboard allows developers to make requests against a live PostgREST server, provides guidance with request headers and example request bodies. - -.. note:: - - The OpenAPI information can go out of date as the schema changes under a running server. To learn how to refresh the cache see :ref:`schema_reloading`. - .. _resource_embedding: Resource Embedding @@ -485,3 +474,14 @@ To delete rows in a table, use the DELETE verb plus :ref:`h_filter`. For instanc .. note:: Beware of accidentally delting all rows in a table. To learn to prevent that see :ref:`block_fulltable`. + +OpenAPI Support +=============== + +Every API hosted by PostgREST automatically serves a full `OpenAPI `_ description on the root path. This provides a list of all endpoints, along with supported HTTP verbs and example payloads. + +You can use a tool like `Swagger UI `_ to create beautiful documentation from the description and to host an interactive web-based dahsboard. The dashboard allows developers to make requests against a live PostgREST server, provides guidance with request headers and example request bodies. + +.. note:: + + The OpenAPI information can go out of date as the schema changes under a running server. To learn how to refresh the cache see :ref:`schema_reloading`. From 3c482a82937c7011d3f229b2bc9869728a3ddca2 Mon Sep 17 00:00:00 2001 From: SteveBash Date: Thu, 23 Mar 2017 12:45:15 -0500 Subject: [PATCH 3/3] Add section for binary output --- api.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/api.rst b/api.rst index c3c1c3c7c..46b9411ee 100644 --- a/api.rst +++ b/api.rst @@ -210,6 +210,7 @@ The current possibilities are * text/csv * application/json * application/openapi+json +* application/octet-stream The server will default to JSON for API endpoints and OpenAPI on the root. @@ -243,6 +244,21 @@ This returns Admittedly PostgREST could detect when there is an equality condition holding on all columns constituting the primary key and automatically convert to singular. However this could lead to a surprising change of format that breaks unwary client code just by filtering on an extra column. Instead we allow manually specifying singular vs plural to decouple that choice from the URL format. +Binary output +------------- + +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`. + +.. code:: http + + GET /items?select=bin_data&id=eq.1 HTTP/1.1 + Accept: application/octet-stream + +.. note:: + + If more than one row would be returned the binary results will be concatenated with no delimiter. + .. _resource_embedding: Resource Embedding