parent 插入和 parent + joinId 使用相同端点插入的 REST 约定

Question

在事件管理系统的上下文中，发言者在不同的 sessions 讲话。我的实体是 Speakers 和 Sessions

假设终点是

1) POST /speakers（仅插入演讲者的详细信息）

2) POST /speakers（插入演讲者的详细信息 + 他正在讲话的 session 的 ID）

点 2 需要在连接中进行额外的插入 table。

如何在同一个端点内指定两种操作。

Answer 1

可以代表一位演讲者，包括他演讲的session。例如：

{
  "id": 1234,
  "firstname": "Joe",
  "lastname": "Doe",
  "sessions": []
}

此表示表示说话者 未在任何 session 上发言。 sessions 是一个空数组。正在做

POST /speakers
Content-Type: application/json

使用如上所示的 JSON 主体，将 创建扬声器 。

如果客户 事先知道所有 session 演讲者将要发言的 ，JSON 可能如下所示：

{
  "id": 1234,
  "firstname": "Joe",
  "lastname": "Doe",
  "sessions": [
    {
      "id": 12,
      "link": "/session/12"
    },
    {
      "id": 34,
      "link"; "/session/34"
    }
  ]
}

对于每个 session 发言者，包含仅包含 id 的短 object 和 session 的 link .这应该足以让服务器知道如何在数据库中 link 扬声器和 sessions。

现在让我们考虑这样一种情况，客户事先不是知道一位发言人将在session上发言。客户端将使用上面的第一个 JSON 表示创建扬声器，包括一个空 sessions 数组。稍后，当客户知道所有 session 发言者将要发言的内容时，他会发出 PATCH 请求：

PATCH /speakers/1234
Content-Type: application/json

{
  "sessions": [
    {
      "id": 12,
      "link": "/session/12"
    },
    {
      "id": 34,
      "link"; "/session/34"
    }
  ]
}

请注意，现在我们只发送 sessions。演讲者的所有其他属性应保留在服务器上。

如果客户想要将session一个接一个地添加到扬声器，他可以对每个session:

POST /speakers/1234/sessions
Content-Type: application/json

{
  "id": 43,
  "link": "/sessions/43"
}

这意味着："add session 43 to the list of sessions of speaker 1234"。这里 /speakers/1234/sessions 是 /speaker/1234 的 子资源 。添加到它是有道理的（当然服务器必须检查重复项）。

注意 POST 的不同用法创建新资源（演讲者），添加到子资源（sessions 的列表）。另请注意 仅更改资源（演讲者）的一部分 使用 PATCH.

编辑：

如果客户端想要发送资源的完整表示，通常使用 HTTP 动词 PUT。将 session 的列表添加到现有说话者时，我们在说话者上使用 PATCH，因为对他使用 PUT 需要客户端发送 的完整表示演讲者。在这个用例中，客户端不想这样做，他想设置 sessions.

的列表

另一种方法是

PUT /speakers/1234/sessions
Content-Type: application/json

[
  {
    "id": 12,
    "link": "/session/12"
  },
  {
    "id": 34,
    "link"; "/session/34"
  }
]

在 子资源 sessions 上 session 的完整列表。请注意区别：此处客户端正在为演讲者发送 session 列表的完整表示。这里PUT表示："Overwrite the complete list of sessions for this speaker with what I provide".

使用 /speakers?eventId=1 获取甚至 1 的发言人列表是一个很好的做法。这里客户端请求 collection 资源 /speakers 的 过滤子集 。使用查询参数表达过滤条件很常见

关于此类知识的好资源，我的一般建议是始终考虑资源。您的 API 提供哪些资源？不同类型的资源如何关联？它们可以相邻存在吗（一个扬声器可以没有 session，一个 session 可以没有扬声器存在），或者是复合材料（酒店房间只能存在于酒店内部）。通常这种问题会有所帮助。但是在 REST 中，没有硬性规定或 "standards" 来规定 URL 必须的构建方式。我认为在 API.

中保持一致很重要

parent 插入和 parent + joinId 使用相同端点插入的 REST 约定

REST convention for parent insert and parent + joinId insert using same endpoint

rest

uri

naming-conventions