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

Question

一个标准的 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呢？

Answer 1

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

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

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

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

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

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

这种方法没有路径歧义。