资源表示#

PostgREST使用适当的HTTP内容协商 (RFC7231 )以提供资源表示。也就是说，相同的API端点可以根据请求以不同的格式(如JSON或CSV)进行响应。

响应格式#

使用Accept请求标头指定响应的可接受格式：

curl "http://localhost:3000/people" \
  -H "Accept: application/json"

内置媒体类型处理程序#

内置处理程序可用于常见的标准媒体类型。

  • text/csv 和 application/json ，用于所有API端点。看见 表和视图 和 作为RPC的功能 。

  • application/openapi+json ，用于根终结点。看见 OpenAPI 。

  • application/geo+json ，见 邮政地理信息系统 。

  • */* ，决心 application/json 对于API端点和 application/openapi+json 用于根终结点。

还支持以下供应商媒体类型处理程序。

任何无法识别的媒体类型都将引发错误。

curl "http://localhost:3000/people" \
  -H "Accept: unknown/unknown"

HTTP/1.1 415 Unsupported Media Type

{"code":"PGRST107","details":null,"hint":null,"message":"None of these media types are available: unknown/unknown"}

要扩展接受的媒体类型，您可以使用 媒体类型处理程序 。

单数或复数#

默认情况下，PostgREST返回数组中的所有JSON结果，即使只有一项也是如此。例如，请求 /items?id=eq.1 退货

[
  { "id": 1 }
]

这可能会给客户端代码带来不便。若要将第一个结果作为未被数组包围的对象返回，请指定 vnd.pgrst.object 作为该计划的一部分 Accept 标题

curl "http://localhost:3000/items?id=eq.1" \
  -H "Accept: application/vnd.pgrst.object+json"

这就是回报

{ "id": 1 }

使用一个 Content-Type: application/vnd.pgrst.object+json 。

当请求单个响应但未找到条目时，服务器会返回错误消息和406不可接受状态代码，而不是通常的空数组和200状态：

{
  "message": "JSON object requested, multiple (or no) rows returned",
  "details": "Results contain 0 rows, application/vnd.pgrst.object+json requires 1 row",
  "hint": null,
  "code": "PGRST505"
}

备注

许多API使用特殊的嵌套URL约定来区分复数和单数资源，例如 /stories VS /stories/1 。为什么我们要使用 /stories?id=eq.1 ？答案是因为单一资源是(对我们来说)由主键确定的行，而主键可以是复合的(意味着跨多个列定义)。更熟悉的嵌套URL只考虑简单且绝大多数是数字的主键的退化情况。这些所谓的人工键通常是由对象关系映射库自动引入的。

诚然，当构成主键的所有列上存在相等条件时，PostgREST可以检测到，并自动转换为单数。然而，这可能会导致令人惊讶的格式变化，仅仅通过过滤额外的列就会破坏粗心的客户端代码。相反，我们允许手动指定单数和复数，以将选择与URL格式分离。

已剥离的空值#

默认情况下，PostgREST返回所有JSON空值。例如，请求 /projects?id=gt.10 退货

[
  { "id": 11, "name": "OSX",      "client_id": 1,    "another_col": "val" },
  { "id": 12, "name": "ProjectX", "client_id": null, "another_col": null },
  { "id": 13, "name": "Y",        "client_id": null, "another_col": null }
]

在大型结果集上，未使用的键 null 值可能会不必要地浪费带宽。要删除它们，请指定 nulls=stripped 作为的参数 application/vnd.pgrst.array ：

curl "http://localhost:3000/projects?id=gt.10" \
  -H "Accept: application/vnd.pgrst.array+json;nulls=stripped"

这就是回报

[
  { "id": 11, "name": "OSX", "client_id": 1, "another_col": "val" },
  { "id": 12, "name": "ProjectX" },
  { "id": 13, "name": "Y"}
]

请求正文#

服务器处理以下请求正文媒体类型：

  • application/json

  • application/x-www-form-urlencoded

  • text/csv

为 表和视图 此功能适用于 POST ， PATCH 和 PUT 方法：研究方法。为 作为RPC的功能 ，它可以在 POST 方法：研究方法。

对于函数，还有三种附加类型：

  • application/octet-stream

  • text/plain

  • text/xml

看见 具有单个未命名参数的函数 。