Singular response for PATCH request (#634)

* Allow a singular entity to be returned from an update

Since a `PATCH` will be an update that could affect many rows, there might be
more than one object returned. By allowing asking for a singular response,
the/an object will be returned instead of a list. This is useful in cases when
the `PATCH` is against single entity (i.e. `/items?pkey=eq.99`).

* Add tests for plurality=singular for `PATCH` requests

* Disallow updating more than one row if `plurality=singular`

As discussed in #634, we don't want to allow updating several rows with
a `PATCH` request when the `Prefer` header specifies
`return=representation;plurality=singular` as this would almost
certainly be a client error.

* Add test for patching multiple objects with singular response

Patching > 1 object with `return=representation;plurality=singular`
should return `400 Bad Request`.

* Only add singleton range for read API requests

* Disallow inserting more than one row if `plurality=singular`

Disallow inserting several rows with a `POST` request when the `Prefer`
header specifies `return=representation;plurality=singular` as this
would almost certainly be a client error.

* Only import `q` from `Text.InterpolatedString.Perl6`

* Update OpenAPI response for PATCH/POST to mention `plurality=singular`

The OpenAPI response for PATCH/POST requests now includes the `Prefer` value
`return=representation;plurality=singular`.

* Add entry in changelog

src/PostgREST/OpenAPI.hs

@@ -162,13 +162,10 @@ makeGetParams cs =
   , makePreferParam ["plurality=singular", "count=none"]
   ]
 
-makeReturnPreferenceParam :: Param
-makeReturnPreferenceParam =
-  makePreferParam ["return=representation", "return=minimal", "return=none"]
-
 makePostParams :: Text -> [Param]
 makePostParams tn =
-  [ makeReturnPreferenceParam
+  [ makePreferParam ["return=representation", "return=representation;plurality=singular",
+                     "return=minimal", "return=none"]
   , (mempty :: Param)
     & name        .~ "body"
     & description ?~ tn
@@ -178,7 +175,7 @@ makePostParams tn =
 
 makeDeleteParams :: [Param]
 makeDeleteParams =
-  [ makeReturnPreferenceParam ]
+  [ makePreferParam ["return=representation", "return=minimal", "return=none"] ]
 
 makePathItem :: (Table, [Column], [Text]) -> (FilePath, PathItem)
 makePathItem (t, cs, _) = ("/" ++ unpack tn, p $ tableInsertable t)