嵌套资源子数组的API设计

Question

我目前正在开发教育应用的API。这是一个教师资源，每个教师都有他们教授的科目列表。目前，GET教师端点如下所示：

{
    "first_name" : "Mister"
    "last_name" : "Teacher"
    "subjects" : [
        {
             "name" : "English",
             "icons" : "/english-icon.png"
             "id" : 1
        },
        {
             "name" : "Math",
             "icons" : "/math-icon.png"
             "id" : 2
        }   
    ]
}

但是，对我来说，在创建和更新主题时发送整个主题对象没有意义，因此POST和PUT学生端点接受以下形式的参数：

{
    "first_name" : "Mister"
    "last_name" : "Teacher"
    "subject_ids": [1,2]
}

不一致似乎很难看，并强制客户端应用程序在将对象发送到服务器之前修改对象的格式。有更优雅的解决方案吗？

Answer 1

首先，您应该包含指向每个主题的链接，而不仅仅是ID。这允许客户端导航到主题，而无需从模式（哪个？）和ID构建URL。

其次，如果你在表达中思考，你的方法就没问题了。两个JSON结构都是同一资源的表示。但他们使用不同的格式。在HTTP客户端和服务器中，使用内容协商会告诉对方他们发送，请求或理解的格式。

如果你这样做，那你就是RESTful。