RESTful API - URI结构建议

Question

我有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结构应该是什么？

Answer 1

IRI 的路径和查询部分由您决定。路径用于分层数据，如api/version/module/collection/item/property，查询用于非分层数据，如?display-fields="id,name,etc..."or?search="brown teddy bear"&offset=125&count=25等​​......

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

重要的是单个 IRI 始终只属于单个资源。因此，您无法使用 读取猫属性并GET /cats/123使用 写入狗属性PUT /cats/123。人们通常不明白的是，单个资源可以有多个 IRI，因此，例如/cats/123、/cats/name:kitty、/users/123/cats/kitty、cats/123?fields="id,name"等...可以属于同一资源。或者，如果您想为某个事物（活猫，而不是描述它的文档）提供 IRI，那么您可以使用/cats/123#thingor/users/123#kitty等​​...您通常在 RDF 文档中这样做。

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

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

您也可以使用查询，但我不建议这样做。例如，以下 IRI 可以有 2 个不同的含义：/api/contacts?name="John"。您想要列出名为 John 的每个联系人，或者您想要一个确切的联系人。因此，您必须在服务器端应用程序的路由器中对此类请求做出一些约定。