【翻译】RAML1.0规范: RESTful API模型语言（0）- 引言

摘要

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