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结构应该是什么?

IRI的路径和查询部分取决于您.路径用于分层数据,如api / version / module / collection / item / property,查询用于非分层数据,如?display-fields =“id,name等…”或?search =“棕色泰迪熊“& offset = 125& count = 25等…

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

重要的是单个IRI始终只属于单个资源.所以你不能用GET / cats / 123读取cat属性,用pUT / cats / 123写狗属性.什么人通常不明白,单个资源可以有多个IRI,例如/ cats / 123,/ cats / name:kitty,/ users / 123 / cats / kitty,cats / 123?fields =“id,名称“等等……可以属于同一资源.或者如果你想给一个东西(活猫,而不是描述它的文件)提供IRI,那么你可以使用/ cats / 123#thing或/ users / 123#kitty等…你通常这样做在RDF文件中.

What should be URI structure be if I want to be able to fetch contact
by either ID or Alias?

它可以是/ api / contacts / name:{name}例如/ api / contacts / name:John,因为它显然是分层的.或者您可以检查/ api / contacts / {param}中的参数是否包含数字或字符串.

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

本站公众号
   欢迎关注本站公众号,获取更多程序园信息
开发小院