raml 语法 - 嵌套 API 资源名称 - 大括号的使用

Posted

技术标签:

【中文标题】raml 语法 - 嵌套 API 资源名称 - 大括号的使用【英文标题】:raml syntax - nested API resources name - usage of curly braces 【发布时间】:2016-01-17 07:58:32 【问题描述】:

一个标准的 raml 例子:

#%RAML 0.8

title: World Music API
baseUri: http://example.api.com/version
version: v1
/songs:
  get:
  post:
  /songId:
    get:
    delete:

资源是:

http://example.api.com/version/songs
http://example.api.com/version/songs/songId

所以,如果我想在这个文档中添加更多的 API,我可以这样做:

http://example.api.com/version/books

我的问题是,以下是否合法?

http://example.api.com/version/songs/upload

如果是,raml 如何区分以下 API? (例如,“上传”的 songId)

http://example.api.com/version/songs/upload
http://example.api.com/version/songs/songId
http://example.api.com/version/songs/upload/songId

如果不是,那么只要花括号 出现在任何级别,就不能为该级别定义更多资源?那么在这种情况下我应该如何定义上传API呢?

【问题讨论】:

【参考方案1】:

我认为 RAML 没有针对不明确的资源 URI 的规定。但是您用于实现 API 的工具可能无法区分它们。

IMO 真正的限制是您希望为 API 的消费者提供的用户体验。

在您的情况下,您可以在此处发布一首新歌曲的详细信息:

http://example.api.com/version/songs

然后在那里发布它的字节数据:

http://example.api.com/version/songs/songId/data

这种方法没有路径歧义。

【讨论】:

您能否详细说明“RAML 没有针对不明确的资源 URI 的规定。”? 抱歉不清楚。我的意思是 RAML 规范不会阻止定义具有不明确匹配的资源。我发现的唯一限制与避免路径参数值中的斜杠有关:github.com/raml-org/raml-spec/blob/master/…,这很明显。 我明白了。那么是我的实现决定http://example.api.com/version/songs/upload 是用于上传功能还是与 id == "upload" 的歌曲有关? 是的,就是这样。

以上是关于raml 语法 - 嵌套 API 资源名称 - 大括号的使用的主要内容,如果未能解决你的问题,请参考以下文章

RAML:在资源中引用 uriParameters

RAML 默认信封

如何包含对 raml 资源的常见响应

RAML 资源类型和特征 VS Swagger $ref

RAML:嵌套模式

如何使用 RAML 描述使用 OAuth2 的 API [关闭]