参考
RESTful API 设计指南-阮一峰
Coding-API：http://api-doc.coding.io/

Restful API概念

域名

一般使用https协议，尽量将接口放在同一域名下，版本号也可以体现在域名中。如：
https://www.example.com/api/v1

资源路径

在Restful架构中，每个路径代表一个资源，命名使用名词如：
人员
https://www.example.com/api/v1/people
商品
https://www.example.com/api/v1/products

HTTP动词

RestfulAPI中，一个资源的路径是固定的，通过使用不同的HTTP动词表示增删改查逻辑。

基础的操作有以下5个：

• GET（SELECT）：从服务器取出资源（一项或多项）。

• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE（DELETE）：从服务器删除资源。

如对于资源“人员”，可以有以下操作：

• GET /people : 获取人员列表

• GET /people/{id} : 获取某个人员详情
• POST /people : 添加一个新的人员
• PUT /people/{id} : 修改人员信息
• DELETE /people/{id} : 删除人员

过滤信息

一些常用的过滤信息作为参数填写，如
GET /people?pageIndex=1&pageSize=10

---

RAML

RAML语言基础

RAML 是一种 RESTful API 的建模语言。
RAML 规格说明：http://raml.org/spec.html
RAML 基础文档：http://raml.org/docs.html
RAML 进阶文档：http://raml.org/docs-200.html

RAML相关工具

RAML可以用任何文本编辑器编写，官方的编辑器主要有api-desinger和api-workbench，不过不知为何，我下的api-desinger版本不能导出项目和预览，而且api-desinger是基于浏览器的网页应用，使用还是不太方便，所以推荐使用api-workbench。

Node.js

下面的工具会使用npm安装，npm是Node.js的包管理器，所以我们需要安装Node.js。
Node.js官网：https://nodejs.org/en/
但是，在国内，使用npm时速度很慢，推荐使用淘宝的npm镜像
淘宝npm镜像：https://npm.taobao.org/

api-designer

官网: https://www.mulesoft.com/platform/api/anypoint-designer
git: https://github.com/mulesoft/api-designer
api-designer是基于Node.js的，使用npm安装：
$ npm install -g api-designer
安装完成后，运行api-designer
$ api-designer

api-workbench

官网：http://apiworkbench.com/
api-workbench是Atom编辑器的插件，先下载Atom：https://atom.io/
在Atom的设置中，选择install，搜索api-workbench，进行安装，速度很慢~

JSON Schema

在编写RAML的过程中，可能会用到JSON Schema，用来描述一些JSON格式。
JSON Schema 是一种用于描述/验证 JSON 数据的结构的声明方式。
官网:：http://json-schema.org/
学习文档：http://spacetelescope.github.io/understanding-json-schema/
在线验证：http://jsonschema.net/#/

生成HTML

最后，通过 raml2html 生成html。
这个工具也是用npm下载。
生成 index.html 的命令为：
$ sudo raml2html api.raml > api.html