синтаксис raml - имя вложенных ресурсов API - использование фигурных скобок

Стандартный пример 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 загрузки в этом случае?


yaml api api-design raml
person Weishi Z    schedule 19.10.2015    source источник

Ответы (1)


arrow_upward
0
arrow_downward

Я не думаю, что в RAML предусмотрена защита от неоднозначных URI ресурсов. Но инструменты, которые вы используете для реализации своего API, могут не различать их.

IMO, реальным ограничением является пользовательский опыт, который вы хотите предоставить потребителям вашего API.

В вашем случае можно было бы разместить информацию о новой песне здесь:

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

затем отправьте туда данные байтов:

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

При таком подходе нет двусмысленности пути.

person David Dossot    schedule 19.10.2015
comment
Не могли бы вы подробнее рассказать о том, что RAML не имеет защиты от неоднозначных URI ресурсов? - person Weishi Z; 19.10.2015
comment
Извините за неясность. Я имел в виду, что спецификация RAML не запрещает определять ресурсы с неоднозначным соответствием. Единственное ограничение, которое я обнаружил, связано с избеганием косых черт в значениях параметров пути: github.com/raml-org/raml-spec/blob/master/ , что очевидно. - person David Dossot; 19.10.2015
comment
Я понимаю. так это моя реализация, которая решает, является ли http://example.api.com/{version}/songs/upload функцией загрузки или речь идет о песне, чей идентификатор == upload? - person Weishi Z; 20.10.2015
comment
Да, это так. - person David Dossot; 20.10.2015