REST API POST：在 url 与 json 主体中传递外键

Question

假设我有两个对象：Student 和 Homework。 Homework 有 Student 作为 fk:

CREATE TABLE student (
    id serial PRIMARY KEY,
    name varchar(100)
)

CREATE TABLE homework (
    id serial PRIMARY KEY,
    topic varchar(255),
    student_id int REFERENCES student(id)
)

对于构造 CRUD API 端点的正确方法是否有任何约定？
如果我想为学生创建新的家庭作业，我可以发送带有学生 ID

的 json 正文

{
    "student_id": 1,
    "topic": "topic
}

到POST https://website.com/api/v1/homework.

或者我可以发送

{
    "topic": "topic
}

到 POST https://website.com/api/v1/students/{student_id}/homework 并从 URL.

中获取学生 ID

在第二种情况下，我将发送一个 POST 请求，其中包含不完整的字段，在第一种情况下，我将有一个额外的端点（因为无论如何我都需要 /students/{id}/homework 来获取特定学生的作业。）

Answer 1

您有两个实体 Student 和 Homework。 Homework 个实体属于 Student。

所以语义上更正确的方法是：

创建作业端点：

POST https://website.com/api/v1/students/{student_id}/homeworks/add

删除作业终点：

DELETE https://website.com/api/v1/homeworks/{homework_id}

没有商定的规则，但这通常是一种广泛遵循的模式：

如果 A 拥有 B，并且您想创建一个新的 B 实体，您的路径将类似于 /A/{A_Id}/B/add。

样板请求：

POST /ParentEntity/ParentId/ChildEntity/add

现在 B 已创建，并且您有一个与之关联的 id，因此您可以直接更改 B（比如对于任何变异操作，POST，DELETE, PUT, PATCH).

DELETE /B/{id}

PUT /B{id}

或

POST /B/{id}/delete

POST /B/{id}/update

（这个跟在Whosebug后面，你的请求intention/action是在URL后缀中定义的，而不是由你的HTTP方法定义的）

为什么我们直接修改B？为什么不做这样的事情：

DELETE /A/{Aid}/B/{Bid}

因为/A/{Aid}是多余的信息。因为保证 {Bid} 始终是唯一的，即使多个 B 实体可以属于单个 A 实体。

其他参考资料：

您可以在此处查看 Whosebug 用于其 API 的 API 模式，以供将来参考。 https://api.stackexchange.com/docs?tab=category#docs

REST API POST：在 url 与 json 主体中传递外键

REST API POST: passing foreign key in url vs json body

rest

api-design

没有商定的规则，但这通常是一种广泛遵循的模式：

为什么我们直接修改B？为什么不做这样的事情：

其他参考资料：

REST API POST：在 url 与 json 主体中传递外键

REST API POST: passing foreign key in url vs json body

rest

api-design

没有 商定的规则，但这通常是一种广泛遵循的模式：

为什么我们直接修改B？为什么不做这样的事情：

其他参考资料：

没有商定的规则，但这通常是一种广泛遵循的模式：