【翻译】RAML1.0规范: RESTful API模型语言（1）- 根节点

引言

本规范描述了RESTful API建模语言（RAML）。RAML是用于定义RESTful应用程序编程接口（API）的人机交互语言。RAML旨在通过提供API提供者和API消费者可以用作相互契约的格式来改进API的规范。例如，便于为客户端和服务器实现提供用户文档和源代码存根。这样的设置简化和增强了使用RESTful API的可互操作应用程序的定义和开发。

RAML引入了资源类型和特征的创新概念，用于表征和重用资源模式和相关方法。使用资源类型和特性可最大限度地减少RESTful API设计中的重复，并提高API内部和跨API的一致性。

本文件组织如下：

• 基本信息. 如何描述API的核心方面，例如其名称，标题，位置（或URI）和默认值，以及如何包括API的支持文档。
• 数据类型. 通过包含JSON和XML模式的流线型类型系统来建模API数据。
• 资源. 如何在任何URI模板中指定API资源和嵌套资源，以及URI参数。
• 方法. 如何指定API资源及其请求标头，查询参数和请求正文的方法。
• 响应. API响应的规范，包括状态代码，媒体类型，响应头和响应正文。
• 资源类型和特征. 可选地使用RAML资源类型和特征来表征资源。
• 安全. 在RAML中指定API安全方案。
• 注释. 通过定义强类型的注释并在整个规范中应用它来扩展RAML规范。
• 包含，库，覆盖和扩展. API定义如何由外部化定义文档组成，将这些定义的集合打包到库中，在RAML文档上分离和覆盖元数据层，以及扩展具有附加功能的API规范。

RAML 1.0中的新增功能和不同之处

• 数据类型：一种统一，简化和强大的方式来模拟数据出现在API中的任何地方。
  • 统一覆盖主体，URI参数，标题和查询参数，并且不需要单独的formParameters构造
  • 支持封装XML模式和JSON模式，甚至引用子模式，但在许多情况下，只是消除模式
  • 通过基于YAML的方式，简化了与JSON模式或XML模式的编码
• 示例：多个示例，可在YAML中表达，并且可注释，因此可以注入语义
• 注释：一个经过测试的，强类型的可扩展性机制
• 库：改进的模块化，用于广泛重用API工件
• 覆盖和扩展：通过分隔文件增加可扩展性
• 改进的安全计划：
  • 更广泛的OAuth支持
  • 支持传递（基于密钥）安全方案
• 一些更小的更改一致性和表达性

标记语言

本规范使用YAML 1.2作为其基本格式。YAML是一种人类可读的数据格式，与本规范的设计目标一致。与YAML中一样，所有节点（如键，值和标记）都区分大小写。

RAML API定义是符合YAML 1.2标准的文档，以符合要求的YAML注释行开头，指示RAML版本，如下所示：

#%RAML 1.0
title: My API

RAML API定义文档的第一行必须以文本开头， #%RAML后跟一个空格，后跟文本1.0，并且在当前行尾前没有其他的东西。RAML片段文档类似地开始于RAML版本注释和片段标识符，但不是自己的RAML API定义文档。

媒体类型application / raml yaml及其关联的文件扩展名.raml应用于指定包含RAML API定义，RAML片段和包含RAML标记的文件的文件。RAML还能够包括其他媒体类型的文档，诸如“application/schema+json”和“application/yaml”。

为了方便RAML文档的自动处理，除了核心YAML 1.2规范之外，RAML还强加了以下限制和要求：

• RAML文件的第一行由指定RAML版本的YAML注释组成。因此，RAML处理器不能完全忽略所有YAML注释。
• RAML文档中某些级别的某些属性的顺序很重要。因此，期望处理器保持这种排序。

文档的根

RAML文档的根部分描述了有关API的基本信息，例如其标题和版本。根部分还定义在RAML文档中其他位置使用的资产，例如类型和特性。

RAML记录的API定义中的节点可以按任何顺序出现。处理器必须在定义树的同一节点内保持相同类型的节点的顺序。这样的节点的示例是出现在资源树的相同级别的资源，给定资源的方法，给定方法的参数和给定类型中相同级别的节点。处理器还必须保持数组中项的顺序。

此示例显示了GitHub v3公共API的RAML API定义的一小部分。

#%RAML 1.0
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType:  application/json
securitySchemes:
  oauth_2_0: !include securitySchemes/oauth_2_0.raml
types:
  Gist:  !include types/gist.raml
  Gists: !include types/gists.raml
resourceTypes:
  collection: !include types/collection.raml
traits:
securedBy: [ oauth_2_0 ]
/search:
  /code:
    type: collection
    get:

下表列出了RAML文档根目录下的可能节点：

名称	描述
title	API的简短纯文本标签。它的值是一个字符串。
description?	一个实质的，人性化的API描述。它的值是一个字符串，可以使用 markdown.格式化。
version?	API版本，例如“v1”。它的值是一个字符串。
baseUri?	一个URI作为全部资源的 base for URIs 。通常用作包含API位置的每个资源的URL的基础. 可以是一个 模板URI。
baseUriParameters?	命名参数中使用的baseUri (模板)。
protocols?	API支持的协议。
mediaType?	请求体和响应体 (负载)所使用的默认媒体类型。 例如 "application/json"。
documentation?	API的其他总体 文档。
schemas?	等效“types”节点的别名，以与RAML 0.8兼容。已弃用-API,定义应使用"types"节点，因为将来的RAML版本可能会删除该节点的“schemas”别名。“types”节点支持XML和JSON模式。
types?	在API中使用的 (数据) 类型的声明。
traits?	在API中使用的 特征的声明。
resourceTypes?	在API中使用的资源类型的声明。
annotationTypes?	注释中使用的注释类型的声明。
(<注释名>)?	要应用于此API的注释。注释是以"("开始，以")"结束的映射,括号中的文本是注释名称，并且该值是该注释的实例。
securitySchemes?	在API中使用的安全方案的声明。
securedBy?	适用于API中每个资源和方法的安全方案。
uses?	在API中使用导入的 外部库。
/<相对Uri>?	API的资源，标识为以斜杠（/）开头的相对URI。资源节点是以斜杠开头的，位于API定义的根或资源节点的子节点。例如，/ users和/ {groupId}。

“schemas”和“types”节点是相互排斥和同义的：处理器不能允许在API定义的根级指定两者。我们建议使用“types”节点而不是“schemas”，因为模式别名已过时，可能会在将来的RAML版本中删除。

用户文档

The OPTIONAL documentation node includes a variety of documents that serve as user guides and reference documentation for the API. Such documents can clarify how the API works or provide technical and business context.
可选documentation节点包括各种文档，用作API的用户指南和参考文档。这些文档可以阐明API的工作原理或提供技术和业务上下文。

The value of the documentation node is a sequence of one or more documents. Each document is a map that MUST have exactly two key-value pairs described in following table:
文档节点的值是一个或多个文档的序列。每个文档都是一个映射，必须有下表中描述的两个键值对：

名称	描述
title	文档标题。它的值必须是非空字符串。
content	文档的内容。它的值必须是非空字符串，并且可以使用 markdown格式化。

This example shows an API definition having two user documents.
此示例显示具有两个用户文档的API定义。

#%RAML 1.0
title: ZEncoder API
baseUri: https://app.zencoder.com/api
documentation:
 - title: Home
   content: |
     Welcome to the _Zencoder API_ Documentation. The _Zencoder API_
     allows you to connect your application to our encoding service
     and encode videos without going through the web  interface. You
     may also benefit from one of our
     [integration libraries](https://app.zencoder.com/docs/faq/basics/libraries)
     for different languages.
 - title: Legal
   content: !include docs/legal.markdown

基本URI和基本URI参数

可选baseUri节点将URI指定为整个API的标识符，并且可以用于指定提供API的URL（其服务端点），并且其形成其每个资源的URL的基础。baseUri节点的值是必须符合URI规范 RFC2396 或模板URI.的字符串。

如果baseUri值是 模板URI，则以下保留的基本URI参数可用。

URI参数	值
version	根级版本节点的值

在baseUri中出现的任何其他URI模板变量可以在API定义根目录下的baseUriParameters节点中显式地描述。baseUriParameters节点与资源节点上的uriParameters节点具有相同的结构和语义，除了它指定基本URI中的参数，而不是资源的相对URI。

如果baseUri值是模板URI，则以下保留的基本URI参数可用。

#%RAML 1.0
title: Salesforce Chatter REST API
version: v28.0
baseUri: https://na1.salesforce.com/services/data/{version}/chatter

以下示例声明了一个显式基本URI参数。

#%RAML 1.0
title: Amazon S3 REST API
version: 1
baseUri: https://{bucketName}.s3.amazonaws.com
baseUriParameters:
  bucketName:
    description: The name of the bucket

当基本URI以一个或多个斜杠（/）结尾时，在使用该基本URI的资源的绝对路径中省略那些尾部斜线。例如，在以下代码段中，资源的绝对路径为http://api.test.com/common/users和http://api.test.com/common/users/groups。

baseUri: http://api.test.com/common/
/users:
  /groups:

在下面，更多复杂的例子，在多个地方连续的斜线，基本URI中只有尾部斜线被折叠，导致这些资源的绝对路径：//api.test.com//common/，//api.test.com/common/users/，//api.test.com//common//users//groups//。

baseUri: //api.test.com//common//
/:
  /users/:
    /groups//:

协议

可选协议节点指定API支持的协议。如果协议节点未被明确指定，则使用包括在baseUri节点中的一个或多个协议;如果协议节点被明确指定，则节点规范覆盖包括在baseUri节点中的任何协议。协议节点必须是非空的字符串数组，值为HTTP和/或HTTPS，并且不区分大小写。

以下是同时接受HTTP和HTTPS请求的API端点示例。

#%RAML 1.0
title: Salesforce Chatter REST API
version: v28.0
protocols: [ HTTP, HTTPS ]
baseUri: https://na1.salesforce.com/services/data/{version}/chatter

默认媒体类型

指定可选mediaType节点可设置具有正文的响应和请求的默认媒体类型。您不需要在每个主体定义中指定媒体类型。

mediaType节点的值必须是媒体类型字符串序列或单个媒体类型字符串。媒体类型适用于具有正文，预期响应和使用相同媒体类型字符串序列的示例的请求。每个值都需要符合 RFC6838中的媒体类型规范。

此示例显示用于接受并返回JSON格式的正文的API的RAML片段。如果此API规范的其余部分未明确指定另一种媒体类型，则此API接受并返回仅JSON格式的主体。

#%RAML 1.0
title: New API
mediaType: application/json

此示例显示用于接受和返回JSON或XML格式的主体的API的RAML片段。

#%RAML 1.0
title: New API
mediaType: [ application/json, application/xml ]

为API请求或响应的主体显式定义mediaType节点将覆盖默认媒体类型，如以下示例所示。资源/list返回表示为JSON或XML的Person []正文。资源/send通过显式地定义一个application/json节点来覆盖默认的媒体类型。因此，资源/send仅返回JSON格式的主体。

#%RAML 1.0
title: New API
mediaType: [ application/json, application/xml ]
types:
  Person:
  Another:
/list:
  get:
    responses:
      200:
        body: Person[]
/send:
  post:
    body:
      application/json:
        type: Another

默认安全

指定可选securedBy节点为API中的每个资源的每个方法设置默认安全方案并保护。节点的值是安全方案名称的数组。有关详细信息，包括如何通过继承解决多个安全方案的应用程序，请参阅应用安全方案 一节。

以下示例显示了允许通过OAuth 2.0安全方案或OAuth 1.1安全方案进行访问的API。

#%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securedBy: [ oauth_2_0, oauth_1_0 ]
securitySchemes:
  oauth_2_0: !include securitySchemes/oauth_2_0.raml
  oauth_1_0: !include securitySchemes/oauth_1_0.raml