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
  

• 删除作业端点：

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

---

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

如果

A

 拥有 

B

，并且您想创建一个新的 

B

 实体，您的路径将类似于 

/A/{A_Id}/B

。

• 样板请求：
  POST /ParentEntity/ParentId/ChildEntity

现在

B

 已创建，并且您有一个与之关联的 

id

，因此您可以直接更改 

B

（对于任何突变操作，

POST

、

DELETE

、

PUT

、

PATCH

）。 

DELETE /B/{id}

PUT /B{id}

或

POST /B/{id}/delete

POST /B/{id}/update

（这个在

StackOverflow Docs中，您的请求意图/操作是在URL后缀中定义的，而不是由您的HTTP方法定义的）

---

为什么我们直接改变B？为什么不做类似的事情：

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

/A/{Aid}

将是冗余信息。因为可以保证 

{Bid}

 始终是唯一的，即使多个 

B

 实体可以属于单个 

A

 实体。

---

其他参考资料：

您可以在此处查看 Stackoverflow 在其 API 中使用的 API 模式，以供将来参考。

https://api.stackexchange.com/docs?tab=category#docs