宁静的api的设计理念和最佳实践

Question

我有幸选择重新设计我们的主要项目public api。 什么开始作为一个宁静的api的目标，[在许多额外添加的功能之后]最终作为rest / json-rpc不匹配。

所以，是时候重新思考和重新设计了。但是我需要一些关于如何解决一些更复杂的操作的想法。

基本的CURD操作已经实现并且运行正常。

每个资源都由分层slugs访问：

GET /project/fubar/fishes

还添加了区域设置和输出格式：

GET /project/fubar/fishes.en-us.json

好的，现在到了棘手的部分：

项目中的基本资源与具有标题和子节点的文件夹具有相似性。 “文件夹”可以包含子文件夹和项目。

将新文件夹或项目添加到文件夹的最佳做法是什么？

需要PUT / PATCH来更新有关文件夹的信息，而不是将资源链接到它？ 需要POST才能创建新文件夹。

POST /project/fubar/fishes

要添加更多内容，最佳做法是将文件夹区分为文件夹和项目与文件夹链接操作。请记住，链接可以并且将具有另一个名称，然后是目标。与POSIX系统中的符号链接类似。

我的想法是（对现有资源）：

POST /project/fubar/fishes
{
   link: /project/fubar/dogs
   title: DOGS!
   type: folder
}

反过来怎么样;取消关联？

DELETE /project/fubar/fishes/dogs

但这是一个好的设计，还是会在以后回复给我？

Answer 1

使用内容协商

不建议使用它：

GET /project/fubar/fishes.en-us.json

在REST术语中，这是不同的资源，而不是

GET /project/fubar/fishes

但据我了解你的问题，两者都是相同的资源，仅在不同的表示中。

要获取特定表示形式的资源，请使用Content negotiation。

GET /project/fubar/fishers
Accept: application/json
Accept-Language: en-us

项目在哪里？

我没有在您的网址中看到任何内容，只有您称之为“文件夹”的内容。在REST术语中，这些称为集合资源。您可以通过POST向集合资源添加项目。你可以通过DELETE删除一个项目。您可以通过POST更改部件来更改项目的各个部分。您可以通过PUT更新完整项目。

我建议识别收集资源和系统中的项目。