diff options
| -rw-r--r-- | docs/index.md | 46 |
1 files changed, 7 insertions, 39 deletions
diff --git a/docs/index.md b/docs/index.md index a5f16f9..b172dc8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,7 +13,7 @@ ES 1.0.0 是 Echo 规范的第一个投入生产环境的版本，而 Echo 是 # 二、介绍 -Echo 规范（ES），是定义一个标准的、与具体编程语言无关的 RESTful API 的规范。文字跑团(TRPG)游戏是一种基于文字描述和角色扮演的桌上游戏，通常由一个游戏主持人(KP)和多个玩家(PC)组成，通过网络平台进行交流和互动。不同的平台可能有不同的功能和限制，比如群聊、频道、图片、音频甚至视频等，这些都会影响到游戏的体验和效果。为了让水系的文字跑团游戏能够跨平台运行，ES 规定了游戏的基本逻辑、数据结构、接口定义、错误处理等。这样，水系用户的 TRPG 游戏就可以在不同的平台上实现相同或相似的功能，同时也可以方便模型或规则包或插件开发者进行扩展和定制。 +Echo 规范（ES），是定义一个标准的、与具体编程语言无关的 RESTful API 与 Event Defined 规范。文字跑团(TRPG)游戏是一种基于文字描述和角色扮演的桌上游戏，通常由一个游戏主持人(KP)和多个玩家(PC)组成，通过网络平台进行交流和互动。不同的平台可能有不同的功能和限制，比如群聊、频道、图片、音频甚至视频等，这些都会影响到游戏的体验和效果。为了让水系的文字跑团游戏能够跨平台运行，ES 规定了游戏的数据结构、接口定义、错误处理等。这样，水系用户的 TRPG 游戏就可以在不同的平台上实现相同或相似的功能，同时也可以方便模型或规则包或插件开发者进行扩展和定制。 # 三、术语定义 @@ -22,11 +22,7 @@ Echo 规范（ES），是定义一个标准的、与具体编程语言无关的 一（或多）份用来定义或描述一个 Event 以及 API 的文档。 -## 3.2 Path 模板 - -Path 模板指用大括号标记来标记一段 URL 作为可替换的路径参数。 - -## 3.3 Media Types +## 3.2 Media Types 媒体类型定义分散于多处。 媒体类型定义应当符合RFC6838。 @@ -45,13 +41,17 @@ text/plain; charset=utf-8 application/vnd.github.v3.patch ``` -## 3.4 HTTP状态码 +## 3.3 HTTP状态码 HTTP状态码被用来表示一次请求的被执行状态。[RFC7231] 定义了有效的状态码，可以在 [IANA Status Code Registry] 找到已经被注册的状态码的列表。 [RFC7231]: http://tools.ietf.org/html/rfc7231#section-6 [IANA Status Code Registry]: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml +## 3.4 其他术语 + +包含 Window、World、Event、Element等词条，详见 [Term.md](./Term.md)。 + # 四、规范 @@ -66,35 +66,3 @@ HTTP状态码被用来表示一次请求的被执行状态。[RFC7231] 定义了 此后开放 API 规范的相同主版本号下更高次要版本的发布不应当对面向低于此次要版本号开发的工具的造成干扰。因此 1.1.0 版本的规范应当可以在面向 1.0.0 版本规范开发的工具内使用。 任何兼容开放 API 规范 1.*.* 的文档应当包含一个 echo 字段用来表明它使用的规范的语义化版本。 - - -## 格式 - -一份遵从开放 API 规范的文档是一个自包含的 JSON 对象，可以使用 JSON 或 YAML 格式编写。 - -比如一个字段有一组值，用 JSON 格式表示为： - -```json -{ - "field": [ 1, 2, 3 ] -} -``` - -规范内的所有字段名都是**小写**。 - -字段分为两种：固定字段和模式字段。固定字段的字段名是确定的，模式字段的字段名需要符合一定的模式。 - -如果一个对象里有模式字段，那么在这个对象里的模式字段的名字不能有重复的。 - -为了保留在 YAML 和 JSON 格式之间转换的能力，推荐使用 [1.2](http://www.yaml.org/spec/1.2/spec.html) 版本的 YAML 格式，而且还需要符合以下限制： -* Tags 必须被限制在 [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231) 允许的范围内。 -* Keys 必须是 [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346) 规范定义的纯字符串。 - -**注意：** 虽然 API 文档是使用 YAML 或 JSON 格式书写的，但是 API 的请求体和响应体或者其他内容可以是任何格式。 - - -## 文档结构 - -``` -to be... -``` |