我正在为博客 REST API 建模,该 API 具有资源 Blog
、Post
和 Comment
,其 URL 如下:
/api/blogs
/api/blogs/{blogId}
/api/blogs/{blogId}/posts
并且我为所有 Post
和它们的 Comment`s 创建单独的端点:
/api/posts
/api/posts/{postId}
/api/posts/{postId}/comments
鉴于我有 postId
,获取特定 Blog
的 Post
的 RESTful 方式是什么?我有三个想法:
1. /api/posts/{postId}/blog
2. /api/blogs/parent-of-post/{postId}
3. /api/blogs?postId={postId}
对我来说,1.
网址看起来更“漂亮”,但 2.
选项看起来更“合乎逻辑”,因为该端点(例如 /api/blogs/*
)通常用于博客资源。>
第三个选项使用查询字符串作为参数,但我遇到的问题是此端点将根据参数返回不同类型的正文。例如。不带参数 /api/blogs
返回 Blog
资源的集合,而带参数 postId
它将只返回 Blog
的单个实例。我不确定这是否是一件好事(特别是因为我使用的是 ASP.NET Core 和具有强类型返回对象的 C#,因此实现可能很尴尬)。
答案 0 :(得分:1)
获取特定帖子的博客的 RESTful 方式是什么?
真正的答案:任何你想要的。
REST 不关心您为资源标识符使用什么拼写约定。只要您的标识符符合 RFC 3986 所描述的产生式规则,您就可以开始使用了。
/api/blogs?postId={postId}
这是一个完全正常的选择,当您想要使用通用 Web 浏览器时,结果证明是一个非常方便的选择,因为 HTML 表单已经有了标准,可以轻松地使用这种形状创建 URI。
你的另外两个选择都很好;他们失去了对 HTML 表单不友好的一点,但使用 URI template 描述这些标识符仍然很容易。
第三个选项使用查询字符串作为参数,但我遇到的问题是此端点将根据参数返回不同类型的正文
通用 API 使用者不会仅仅因为它们标识符的拼写相互重叠就假设两个资源是相似的。
也就是说,从外部来看,
之间没有任何隐含的关系/api/blogs
/api/blogs/1
/api/blogs?postId=2
因此,对于一般用途的消费者来说,它们返回不同的主体这一事实真的不会让人感到惊讶。
现在,您的路由框架可能不支持从这些资源的处理程序返回不同的类型(或者,更有可能的是,可能没有任何“好”的方式来自动进行路由),但那是故意隐藏在 REST API 外观后面的实现细节。
同样,阅读您的访问日志的人可能更喜欢一种拼写,以减少他们自己的认知负担。