摘要
RAML是一种用于定义基于HTTP协议的API的语言,体现了表述性状态转移(REST)的大部分或全部原则.本文档构成RAML规范,是 YAML 1.2 specification的应用。RAML规范提供了用于定义实际上RESTful API的机制,RAML规范提供了定义几乎真正RESTful的API,创建客户端/服务器源代码,并为用户全面记录API。
本文档的状态
本文档构成RAML 1.0规范。规范作者和RAML 0.8用户的共识决定了本文档的内容,本规范作者和RAML 0.8用户的共识决定了本文档的内容。我们强烈建议RAML 0.8规范的实现者和用户将其软件和API定义更新为RAML 1.0规范。
术语和一致性语言
规范性文本描述以下一种或两种元素:
- 本规范的重要要素
- 包含由 IETF RFC 2119 定义的一致性语言关键字的元素,“在RFC中用于指示需求级别的关键词”
信息文本对用户有潜在的帮助,但可以是不必要的。信息文本可以在编辑时更改,添加或删除,而不会对规范的实现产生负面影响。信息文本不包含一致性关键字。
默认情况下,本文档中的所有文本都是规范性的。
本文档中的关键词“必须(MUST)”,“必须不(MUST NOT)”,“需要(REQUIRED)”,“可以(SHALL)”,“不可以(SHALL NOT)”,“应该(SHOULD)”,“不应该(SHOULD NOT)”,“推荐(RECOMMENDED)”,“可能(MAY)”和“可选(OPTIONAL)”被解释为IETF RFC 2119“在RFC中用于指示需求级别的关键词”中所描述的。
定义和术语
通用的
在本说明书中,API定义表示使用此规范的API
RAML规范指本文档
REST用于使用REST(表述性状态转移)的一些或所有原则实现的API的上下文,REST是在2000年第5章REST,Roy Fielding的博士论文“建筑风格和基于网络的软件架构的设计”*。
资源是到一个实体或一组实体的概念映射
尾部问号,例如description?,表示可选属性。
模板URI
模板URI指的是URI参数,它是一个变量元素,用一个大括号({})括在资源的相对URI中。
RAML完全支持 RFC6570中URL模板的第2级定义。
Markdown
在本说明书中,** Markdown **表示 GitHub-Flavored Markdown