代码之家 › 专栏 › 技术社区 › petabyte

我的API设计是否违反了RESTful原则?

rest architecture api

petabyte · 技术社区 · 14 年前

我目前正在(尝试)为社交网络设计一个RESTfulAPI。但我不确定我目前的方法是否仍然符合休息原则。如果能给我一些建议,我会很高兴的。

假设以下URI表示用户帐户的名称字段:

people/{UserID}/profile/fields/name

但有近百个可能的领域。因此,我希望客户机创建自己的字段视图或使用预定义的字段视图。假设下面的URI表示一个预定义的字段视图,其中包含字段“name”、“age”、“gender”:

utils/views/field-views/myFieldView

因为字段视图是一种更高的逻辑,所以我不想将对字段视图的支持混合到“people/userid/profile/fields”资源中。相反,我要执行以下操作:

utils/views/field-views/myFieldView/{UserID}

另一个例子

假设我们要执行一些数量操作(希望这是正确的英文名称)。我们有以下URI,而每个URI都指向一个人员列表——他们的朋友:

GET people/exampleUID-1/relationships/friends
GET people/exampleUID-2/relationships/friends

现在我们想知道他们中的哪些朋友也是我的朋友。所以我们这样做:

GET people/myUID/relationships/intersections/{Value-1};{Value-2}

鉴于“value-1/2”是“people/exampleuid-1/friends”和“people/exampleuid-2/friends”的URL编码值。然后我们得到所有三个人的朋友的代表。

尽管Leonard Richardson&Sam Ruby在其著作“RESTful Web服务”中指出,RESTful设计在某种程度上类似于“极端面向对象”方法,但我认为我的方法是面向对象的,因此符合RESTful原则。还是我错了?

如果不是:当谨慎使用这种“面向对象”的方法时,为了避免基于查询的REST-RPC混合,通常鼓励这种方法吗?

感谢您的事先反馈,

PETA

3 回复 | 直到 14 年前

MicE 14 年前

嗨,彼得,
我还在看书呢 RESTful Web Services 我自己,但我建议采用一种与提议的稍有不同的方法。

关于你文章的第一部分:

utils/views/field-views/myFieldView/{UserID}

我不认为这是休息,因为 utils 不是资源。定义自定义视图是可以的,但是这些视图应该是(imho)API的URI方案的自然组成部分。要将上述内容合并到第一个URI示例中,我建议使用以下示例之一,而不是为其创建特殊视图:

people/{UserID}/profile/fields/name,age,gender/
people/{UserID}/profile/?fields=name,age,gender

后一个例子考虑 fields 作为算法的输入值。这可能比 领域 在URI中,因为它不是资源本身-它只是对现有的 people/{UserID}/profile/ . 从技术上讲,它非常类似于分页,在这种情况下,您将默认限制视图,并允许客户机使用 ?page=1 , ?page=2 等等。

关于你文章的第二部分:
这是更难破解的。

第一: 有 intersection 在这个URI中,您的URI方案会有一点中断。它本身不是一种资源,而且它与 friends ,而它更适合低于一个级别或作为算法的输入值,即

GET people/{UserID}/relationships/friends/intersections/{Value-1};{Value-2}
GET people/{UserID}/relationships/friends/?intersections={Value-1};{Value-2}

我个人又倾向于后者,因为与第一种情况类似,您只是限制了 people/{UserID}/relationships/friends/

其次 ,关于:

鉴于“value-1/2”是URL 的编码值 “人/示例uid-1/朋友”和 “个人/示例uid-2/朋友”

如果你是那个意思的话 {Value-1/2} 包含上述GET请求的整个编码响应,然后我将避免这种情况——我认为这不是一种休息的方式。自从 朋友 本身就是一个资源,您可能希望公开它并直接访问它,即:

GET friends/{UserID-1};{UserID-2};{UserID-3}

这里有一件重要的事要注意-我用过 ; 在上一个示例中的用户ID之间,而我使用 , 在 领域 上面的例子。理由是两者都代表不同的运算符。在第一种情况下,我们需要 OR ( , )为了得到这三个字段,而在上面的最后一个示例中,我们必须使用 AND ( ; )为了得到一个十字路口。

使用两种类型的运算符可能会使API设计过于复杂,但最终它应该提供更大的灵活性。

Richard Turner 14 年前

我从未使用过REST,但我假设在“”/people/userid/profile“”获取配置文件资源会生成一个包含所有字段的XML或JSON文档。然后我会忽略我不感兴趣的领域。这难道不比(a)在服务器上配置一个个性化的视图或(b)发出大量请求来获取每个字段更好吗?

petabyte 14 年前

谢谢你的澄清回答。它们正是我想要的。不幸的是,我没有时间从头到脚地阅读“RESTfulWebservices”;但我会尽快赶上它。-)

关于我的第一部分:

你说得对。我倾向于你的第一个例子,没有领域。我想我根本不需要它。(目前)您为什么建议使用或(,)而不是和(;)?凭直觉,我会使用and运算符,因为我需要它们中的三个,而不仅仅是第一个。(就像第121页的颜色对示例一样)

关于第二部分:

用 {Value-1/2} 我的意思是只有URL编码的URI值,而不是它们的响应数据。:)在这里,我倾向于举第二个例子。在这里,很明显,在计算相交的朋友时,会用到一个算法。除此之外,我可能会在其中添加一些进一步的操作。

PETA