RESTful API 又叫 Web API, REST 是 representational state transfer 的简写。RESTful API 使用 HTTP 协议的 GET, PUT, POST, PATCH 等操作来定义程序接口。由于这四个操作在 HTTP 协议都有特定的含义,所以我们应该遵循它们的习惯性用法。
- GET 用来查询
- PUT 来修改资源
- POST 用来增加资源或者执行控制命令
- DELETE 用来删除某个资源
- PATCH 用来改变资源的某个属性
在实际应用中由于只改变资源某个属性的情形较少,所以很多情况下会直接使用 PUT 直接修改资源
这些操作都是针对资源 (resource) 的,为了让用户能够直观准确地理解 API 的使用,我们应该遵循以下约定:
资源名称使用小写
所有 API 都会操作某个资源,资源名称应该是小写的复数形式,比如 students。
- 如果是两个单词组成的资源名称,我们使用减号 “-” 来连接这个两个单词,比如 student schools 写作 student-schools。
- 如果是资源的子集则子集放在斜线后
示例
# 查询所有学生
GET /students
# 查询id=996的学生
GET /students/996
# 查询男生
GET /students/male
# 查询年纪15岁男生
GET /stu