RESTful API-URI结构建议

我的REST API URL结构类似于：

/api/contacts                 GET          Returns an array of contacts
/api/contacts/:id             GET          Returns the contact with id of :id
/api/contacts                 POST         Adds a new contact and return it with an id added
/api/contacts/:id             PUT          Updates the contact with id of :id
/api/contacts/:id             PATCH        Partially updates the contact with id of :id
/api/contacts/:id             DELETE       Deletes the contact with id of :id

我的问题是：

/api/contacts/:id             GET

假设除了通过ID获取联系人外，我还希望通过唯一的别名获取联系人

---

如果我希望能够通过ID或别名获取联系人，那么URI结构应该是什么？

如果您是Alias的联系人，那么我建议您使用相同的URI结构，并确定这是您的ID还是别名。就像Facebook使用用户名和用户名一样。Facebook.com/user\u id或Facebook.com/username

另一种方法是让客户端使用带有一些额外GET参数的GET/contacts作为过滤器，首先搜索联系人，然后从该响应中查找ID

---

我认为最后一个选项是使用像GET/contacts/alias/：alias这样的结构。但这意味着别名是联系人的子资源。

< P>我想在尝试用别名解析资源时添加一个“搜索”资源：

GET /api/contacts/:id

及

或

---

首先，URL中的“ID”不必是数据库生成的数字ID。您可以使用URL中的任何数据（包括别名），只要它是唯一的。当然，如果您在任何地方都使用数字ID，那么在contacts API中使用数字ID会更加一致。但是您可以选择使用别名而不是数字ID（只要它们总是唯一的）

根据建议，另一种方法是允许URL中同时使用数字ID和别名：

/api/contacts/123
/api/contacts/foobar

但如果别名可以是数字的，这显然会导致问题，因为这样您就无法区分ID和（数字）别名

最后但并非最不重要的一点是，您可以实现一种过滤整个集合的方法，正如前面所建议的那样。我不会引入

search

资源，因为这不是真正的RESTful，所以我会选择另一种解决方案：

/api/contacts?alias=foobar

---

这将返回所有带有

foobar

别名的联系人。由于别名应该是唯一的，因此将返回1或0个结果。

IRIs的路径和查询部分由您决定。路径用于分层数据，如

api/version/module/collection/item/property

，查询用于非分层数据，如

？display fields=“id，name等…”或
？search=“brown tedy bear”&offset=125&count=25等

您必须记住的是，您使用的是资源，而不是操作。因此，IRI是资源标识符，如
DELETE/something
，而不是操作标识符，如
POST/something/DELETE
。您不必遵循IRIs的任何结构，例如，您可以简单地使用
POST/dashuif328rgfiwa
。服务器会理解，但为这种IRIs编写路由器要困难得多，这就是为什么我们使用漂亮的IRIs

重要的是，单个IRI始终只属于单个资源。因此，您无法使用
GET/cats/123
读取猫的属性，也无法使用
PUT/cats/123
写入狗的属性。ppl通常不理解的是，一个资源可以有多个IRI，例如
/cats/123
，
/cats/name:kitty
，
/users/123/cats/kitty
，
cats/123？fields=“id，name”
，等等。。。可以属于同一资源。或者如果你想给一个东西（活猫，而不是描述它的文档）一个IRI，那么你可以使用
/cats/123#thing
或
/users/123#kitty
，等等。。。您通常在RDF文档中这样做

如果我想获取联系人，URI结构应该是什么
通过ID或别名

它可以是
/api/contacts/name:{name}
，例如
/api/contacts/name:John
，因为它具有明显的层次结构。或者，您可以在
/api/contacts/{param}
中检查参数是否包含数字或字符串

您也可以使用查询，但我不建议这样做。例如，以下IRI可以有两种不同的含义：
/api/contacts？name=“John”
。您想列出每个名为John的联系人，或者您想要一个确切的联系人。因此，您必须在服务器端应用程序的路由器中对此类请求制定一些约定。
回答得好。但是，如果无法以这种方式将ID与别名区分开来，您会有什么建议？我看不到任何其他方式不会破坏REST结构，除了可能执行诸如GET/contacts/alias/：alias之类的操作。但这有点暗示alias是联系人的子资源，“但这有点暗示alias是联系人的子资源。”-是的，但谁需要知道呢？我的意思是，只有API开发人员需要这些信息来为传入消息构建链接和路由器。其他人将只使用链接，并通过检查链接关系来决定导航。。。因此，在我看来，IRI结构是不相关的，IRI不应该成为您文档的一部分。如果他们是ppl，他们可以编写自己构建IRIs的简单客户端…谢谢，/api/contacts/name:{name}看起来非常适合我想要的。您能指出任何使用类似方法的API吗另外，您关于“一个资源可以有多个IRI”的评论，这是一个好做法吗？我的意思是，单个资源拥有多个URI是完全自然的吗？您给出的示例很有意义，我只是想知道这种方法是否与REST API的最佳实践相违背。它只是关于不同IRI的解释，例如
/users
，
/users？page=6
，
/users？search=“Susanne”
。现在这是3个不同的虹膜。我们这里有3种不同的资源，还是只有一种？您可以说，
/users
是一个集合资源，
/users？page=6
是一个页面资源，
/users？search=“Susanne”
是一个地图简化的集合资源，但这并没有真正意义
/api/contacts/123
/api/contacts/foobar

/api/contacts?alias=foobar