api - REST 模式创建、更新和删除相同的端点

Question

我有一个页面，其中列出了学校的书籍。用户可以更新书籍、添加新书或删除现有书籍。提交表单时必须保存所有操作。

我如何为它映射一个 rest API？我可以利用我已有的端点。

更新

PUT /schools/1/books
{
  "books": [
    {
      "id": "1",
      "name": "Book 1"
    }
  ]
}

创建

POST /schools/1/books
{
  "books": [
    {
      "name": "Book 2"
    },
    {
      "name": "Book 3"
    }
  ]
}

删除

DELETE /schools/1/books
{
  "books": [
    {
      "id": 2
    }
  ]
}

但我需要所有东西都在同一个事务上运行，提交 3 个请求没有意义。

我还考虑过创建一个新端点，我可以在其中创建不存在的图书、更新存在的图书以及删除请求中不存在的图书。

所以如果这所学校有Book 1和Book 2，我可以更新Book 1，创建New Book 并删除 Book 2 :

PUT /schools/1/batch-books
{
  "books": [
    {
      "id": "1",
      "name": "Updated Book 1"
    },
    {
      "name": "New Book"
    }
  ]
}

你们还有其他选择吗？

Answer 1

我会将事物分成不同的资源:

• /books 和 /books/{id} 用于书籍。他们提供图书详细信息并允许对其进行管理。
• /schools 和 /schools/{id} 用于学校。他们提供学校详细信息并允许对其进行管理。
• /schools/{id}/books 关联学校的书籍。我的意思是学校内可用的书籍。此资源提供了管理图书链接列表的方法。

让我详细说明最后一个资源。其实这和超媒体有关。在下文中，我将使用 JSON-LD，但您可以自由使用其他超媒体工具。

GET 方法将返回关联书籍的列表:

GET /schools/1/books
[
  {
    "@id": "http://api.example.com/books/1895638109"
  },
  {
    "@id": "http://api.example.com/books/8371023509"
  }
]

您会注意到，如果需要，您可以实现允许获取更多详细信息的机制。利用Prefer header 似乎是一个很好的方法(有关更多详细信息，请参见下面的链接)。

此外，您还可以提供以下方法:

• POST 添加指向学校的链接。请求负载为:{"@id": "http://api.example.com/books/1895638109"}。响应应该是 201 状态代码。

• DELETE 从学校删除特定链接。查询参数可用于指定要删除的链接。

• PATCH 允许在一次调用中执行多个操作，并实际提供一些批处理。您可以在这个水平上利用 JSON-PATCH用于请求处理。在响应中，您可以描述发生了什么。此级别没有规范，因此您可以自由使用您想要的...这是请求有效负载的示例:

    PATCH /schools/1/books/
    [
      {
        "op": "add", "value": "http://api.example.com/books/1895638109"
      },
      {
        "op": "remove", "path": "http://api.example.com/books/8371023509"
      }
    ]
  

阅读以下链接可以为您提供有关设计此类用例的一些提示:

• 在 RESTful 服务中实现批量更新:http://restlet.com/blog/2015/05/18/implementing-bulk-updates-within-restful-services/
• 关于选择超媒体类型:http://sookocheff.com/post/api/on-choosing-a-hypermedia-format/
• 在 API 中创建客户端优化的资源表示:http://www.freshblurbs.com/blog/2015/06/25/api-representations-prefer.html

希望对你有帮助， 蒂埃里