资源表示

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，请参阅 PostGIS.
*/*，对于 API 端点解析为 application/json，对于根端点解析为 application/openapi+json。

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

application/vnd.pgrst.plan，请参阅执行计划.
application/vnd.pgrst.object 和 application/vnd.pgrst.array，请参阅单数或复数和去除空值.

任何无法识别的媒体类型都会抛出错误。

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 }
]

这对于客户端代码来说可能很不方便。为了将第一个结果作为未包含在数组中的对象返回，请在 Accept 标头中指定 vnd.pgrst.object

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 与 /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

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