基于REST的API设计：CRUD轻量级连接最好的方法？ [英] RESTful API design: best way to CRUD lightweight connections?

问题描述

（原谅问题的标题;硬来概括这个问题）

(Pardon the question title; hard to summarize this question.)

在Facebook上，你像的东西。在Twitter上，你遵循的人。在GitHub上，你也遵循人星回购和学家。

On Facebook, you like things. On Twitter, you follow people. On GitHub, you also follow people and star repos and gists.

所有这些情况都是pretty相似：这些连接是轻量级的，不是真正的资源自己。例如。没有这三个的API暴露出公共标识这样的连接。

All of these cases are pretty similar: those connections are lightweight, not really "resources" themselves. E.g. none of those three APIs expose public IDs for such connections.

这引发了一个问题：？什么是最好（REST中的条款）的方式来暴露一个API来创建/查询/删除这些连接

This raises the question: what's the "best" (in terms of REST) way to expose an API for creating/querying/deleting those connections?

的Facebook 确实[ 1 ]：

• GET /：ID /喜欢来查询对象的喜好（更多precisely，用户，象这样的对象）

• GET /:id/likes to query an object's likes (more precisely, the users that like that object)

POST /：ID /喜欢来喜欢的东西（代表auth'ed用户;不需要REQ体）

POST /:id/likes to like something (on behalf of the auth'ed user; no req body needed)

删除/：ID /喜欢来不像的东西（代表auth'ed用户）

DELETE /:id/likes to unlike something (on behalf of the auth'ed user)

查询和创造意义，但删除是一个有点unRESTful，因为你没有真正删除 /：ID /喜欢资源（用户的数组，象这样的对象）。

The querying and creating make sense, but the DELETE is a bit "unRESTful", because you're not actually deleting the /:id/likes resource (an array of users that like that object).

这种差异表现在另一起案件中[ 2 ]：

This discrepancy shows itself in another case [2]:

• GET /我/爱/：ID 查询你是否喜欢的东西

• GET /me/likes/:id to query whether you like something

所以你的查询连接查询一个完全不同的资源比创建或删除它。

So querying your connection is querying a totally different resource than creating or deleting it.

GitHub上倾斜到 /我/爱/：ID 风格以下用户和主演的回购的[< A HREF =htt​​p://developer.github.com/v3/activity/starring/相对=nofollow> 3 ]：

GitHub leans to the /me/likes/:id style for following users and starring repos [3]:

（注意，GitHub的 /用户重新presents的auth'ed用户，像Fac​​ebook这样的 / ME 。）

(Note that GitHub's /user represents the auth'ed user, like Facebook's /me.)

• GET /用户/出演/：业主/：回购用于查询是否已回购出演（返回204或404，没有身体无论哪种方式）

• GET /user/starred/:owner/:repo for querying whether you have a repo starred (returns 204 or 404, no body either way)

PUT /用户/出演/：业主/：回购为主演回购（在没有请求所需的身体）

PUT /user/starred/:owner/:repo for starring a repo (no body needed in request)

删除/用户/出演/：业主/：回购为取消星标回购

这是更加一致的，但不幸的是这分开的各个组的明星：

This is much more consistent, but unfortunately this separates individual "stars" from the group:

• GET /回购/：业主/：回购/​​观星查询谁出演过回购的用户

• GET /repos/:owner/:repo/stargazers to query the users who've starred a repo

GitHub上，有趣的是，使用不同的样式主演的学家的[ 4 ]：

GitHub, interestingly, uses a different style for starring gists [4]:

• GET /学家/：ID /星用于查询你是否有一个要点出演

• GET /gists/:id/star for querying whether you have a gist starred

PUT /学家/：ID /星的主演依据

删除/学家/：ID /星为取消星标一个要点

这保持与精神资源主演的动作，如Facebook，而不是用户的资源。

This keeps the starring action with the gist resource, like Facebook, rather than the user resource.

GitHub上不会公开暴露的学家的观星，但presumably这将会是例如：

GitHub doesn't publicly expose gists' stargazers, but presumably it'd be e.g.:

• GET /学家/：ID /观星查询谁出演过一个要点用户

• GET /gists/:id/stargazers to query the users who've starred a gist

在观星者的确是不同的资源/名称明星，该名称很相似，并明确相关的，他们都在同一资源。

While "stargazers" is indeed a different resource/name than "star", the names are similar and clearly related, and they're both on the same resource.

我能想到的这个唯一的缺点是命名的资源。像星东西的作品，但像的行动遵循或像是棘手。

The only downside I can think of to this is naming the resource. Something like star works, but actions like follow or like are trickier.

（没有打扰到包括Twitter的API作为一个例子，因为它几乎RESTful的。）

(Not bothering to include the Twitter API as an example since it's hardly RESTful.)

有显然创建无完美的RESTful API /查询/删除的东西都是不正确的资源，但有其他的优点/缺点，我没有看到，或者其他样式的考虑？

There's clearly no perfectly RESTful API for creating/querying/deleting things that aren't proper resources, but are there other pros/cons I'm not seeing, or other styles to consider?

谢谢！

推荐答案

有一件事我很喜欢关于 /我/爱/：ID 的风格是，喜欢的不要的感觉像个人，可寻址资源 - 例如他们有各自的ID（即恰好是一样的，我喜欢的事情）。

One thing I liked about the /me/likes/:id style is that the likes do feel like individual, addressable resources -- e.g. they have individual IDs (that happen to be the same as the things I'm liking).

GitHub的的回购的API使用这个很好的创建/查询/删除，以回购协议明星的连接，但有一个为获取的所有的明星的连接对于一个给定的差异回购。

GitHub's repo API uses this nicely for creating/querying/deleting "star" connections to repos, but there's a discrepancy for fetching all "star" connections for a given repo.

也许这种差异可以通过改变你解决这些连接的方式加以解决：不是单纯的对象ID依托，使用（auth'ed）用户的ID了。例如：

Perhaps the discrepancy could be addressed by changing the way you address these connections: instead of relying solely on the object ID, use the (auth'ed) user's ID too. E.g.:

• GET /：业主/：回购/​​观星查询所有谁已经出演这个回购协议的用户

• GET /:owner/:repo/stargazers to query all the users who've starred this repo

GET /：业主/：回购/​​观星/：ID 来查询是否用户：ID 已回购出演！ - 这可能是auth'ed用户通过指定我

GET /:owner/:repo/stargazers/:id to query whether user :id has the repo starred -- this can be the auth'ed user by specifying me!

PUT /：业主/：回购/​​观星/我明星回购 - 这将只对auth'ed用户的工作。

PUT /:owner/:repo/stargazers/me to star a repo -- this'll only work for the auth'ed user

删除/：业主/：回购/​​观星/我来星标回购 - 同上

DELETE /:owner/:repo/stargazers/me to unstar a repo -- ditto

现在所有资源/行动起来，采取的行动是一致的，并命名很容易。

Now all the resources/actions are together, the actions are consistent, and naming is easy.

编辑：这种方法的另一个好处是，你可以很容易地和有效地查询是否的其他的用户喜欢/跟随/星的对象，以及

Another benefit of this approach is that you can easily and efficiently query whether other users like/follow/star an object, as well.

编辑：但是缺点是资源不是技术上是正确的了 - GET ... /观星返回列表的用户的，但 GET ... /观星/：ID 返回一个连接，而不是用户。哦？

But a downside is that the resources aren't technically correct anymore -- GET .../stargazers returns a list of users, but GET .../stargazers/:id returns a connection, not a user. Oh well?

的 [再次编辑，以支持通过我为：ID 过这里]

这篇关于基于REST的API设计：CRUD轻量级连接最好的方法？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！