restful api的设计理念和最佳实践

Question

我有幸重新设计了我们的主项目公共api。最初的目标是创建restful api，但在添加了许多额外功能后，最终导致rest/json-rpc不匹配。

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

基本的CURD操作已经实现，并且运行良好。

每个资源都由分层的slug访问：

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
}

反之亦然: unlink？

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

物品在哪里？

我在你的URL中看不到任何项目，只有你所说的‘文件夹’。在REST术语中，这些资源称为集合资源。通过对集合资源执行POST操作，可以将项添加到集合资源中。通过对项目执行DELETE操作来删除项目。您可以通过将更改的部分POST到项目中来更改项目的部分。你可以通过PUT来更新一个完整的项目。

我建议您确定系统中的集合资源和项目。