Rest api 设计规范

一、Api资源分类

---

根据使用对象以及应用场景不同，我们把Api划分为 免费资源，移动端资源、联合资源。

1、Free 免费资源

地址：/free/****

描述：该类资源主要是用于不涉密公共基础数据服务，在开发前端业务组件时常会使用到该类数据服务。

2、Unity 联合资源

地址：/unity/****

描述：主要提供给web 与 client 使用，该类资源需要进行权限认证。

3、 Mobile 移动资源

地址：/mobile/****

描述：主要提供给移动端使用，该类资源也需要进行权限认证。

二、命名规范

---

1、使用英文全小写，组合词使用“-”连接，尽量不要用英文简写或中文拼音等

三、地址规范

---

1、语意须简要、清晰。所表达的意思要逐级递进

2、对于语意不明确的可采用*****?state=cache 来修饰

四、地址约定

---

4.1 常见场景地址约定设计

1、分页查询

xxxx/department/page

2、条件查询

xxxx/department/query

3、主键获取

xxxx/department/{id}

4、多结果单值条件获取

xxxx/department/list?level=2

5、tree型数据获取

xxxx/department/tree

6、子级数据获取

xxxx/department/child/{parentId}

7、同级数据获取

xxx/department/siblings/{id}

8、父亲数据获取

xxx/department/parent/{childId}

9、祖先数据获取

xxx/department/parents/{childId}

10、所有数据获取

xxx/department/all