【公共规范】URI规范

首先来看一下URI的格式:URI = scheme://authority/path[?query][#fragment ]

  • 1、使用"/"来分割层级,并且层级不要超过三级 【建议】

  • 2、全部使用小写,不能使用大写(包括驼峰) 【强制】,反例:/api/getUserList。正例:/api/users

  • 3、使用连续的"-"代替"_",因为使用"_"会和链接样式重叠 【强制】反例:/api/user_group。正例:api/user-group

  • 4、使用英文单词,不使用中文拼音,除了特定的词语 【强制】

  • 5、URI中的使用名词标识资源集合,并且应该使用复数形式 【强制】

  • 6、参数列表要encode,编码使用utf-8 【强制】

  • 7、增加版本号 【建议】

举例,github的部分api:

功能

api地址

请求方式

请求参数

返回参数

获取用户信息

https://api.github.com/users

GET

path路径: 用户名

一个用户对象

获取用户所有仓库

https://api.github.com/users/{用户名}/repos

GET

path路径: 用户名

返回一个数组

获取某个仓库的详细信息

https://api.github.com/users/{用户名}/{仓库名}

GET

path路径: 用户名、仓库名

返回一个仓库

对象

获取某个仓库里根目录文件或者文件夹数组

https://api.github.com/users/{用户名}/{仓库名}/ccontents

GET

path路径: 用户名、仓库

返回一个首层

文件或文件夹

数组

获取某个仓库里子目录文件

https://api.github.com/users/{用户名}/{仓库名}/ccontents/{文件名或文件夹名}

GET

path路径: 用户名、仓库名、文件名或文件夹名

返回一个文件 数组

O Captain! My Captain!