API 请求

HTTP 动词

HTTP 动词是用来描述 API 请求的动作的，常见的有 GET、POST、PUT、DELETE 等，这些动词都是符合 RESTful API 设计的。

• GET：读取（Read）
• POST：新建（Create）
• PUT：更新（Update）
• PATCH：更新（Update），通常用于部分更新
• DELETE：删除（Delete）

URL 名词

宾语就是 API 中的 URL 名词，它是用来描述 API 请求的对象的，常见的有 users、posts、comments 等，这些名词都是符合 RESTful API 设计的。

/users // ✔ 
/posts // ✔
/articles // ✔
/getAllCars // ✖️
/getAllUsers // ✖️

案例

请求方法	请求路径	作用
GET	/zoos	列出所有动物园
POST	/zoos	新增一个动物园
GET	/zoos/:id	获取某个指定动物园的信息
PUT	/zoos/:id	更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH	/zoos/:id	更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE	/zoos/:id	删除某个动物园
GET	/zoos/:id/animals	列出某个指定动物园的所有动物
DELETE	/zoos/:id/animals/:animal_id	删除某个指定动物园的指定动物

过滤信息

如果数据过多，不能简单地将所有数据都返回给用户，这时就需要过滤信息。过滤信息的方法是在 URL 后面加上查询字符串（query string），即 URL 中加上 ?key=value 的形式，多个查询条件之间用 & 分隔。

GET /zoos?limit=10&offset=20    // 获取前 10 个动物园且跳过前 20 个
GET /zoos?sortby=name&order=asc // 按名称升序排列
GET /zoos?fields=name,area      // 只返回名称和面积两个字段
GET /zoos?name=Beijing          // 只返回北京动物园的信息

参数的设计存在冗余，比如上面的例子中，如果要获取北京动物园的信息，可以直接写成 /zoos/Beijing，而不是通过 name 参数。

特殊情况

CURD （Create、Update、Retrieve、Delete）是最常见的操作，但是 RESTful API 并不限于此，还有一些特殊的操作，比如登录、登出、上传文件等。一般来说，这些操作的 URL 都是固定的，不会随着资源的变化而变化，所以这些操作的 URL 通常都是动词，而不是名词。

POST /login    // 登录
POST /logout   // 登出
POST /upload   // 上传文件

或者某些接口中有特殊的功能，如 /articles/:id/publish。

动词覆盖

有些客户端只能使用 GET 和 POST 两种方法，服务器必须接收用 POST 来模拟其他三个方法。这时，通过 HTTP 发出去的 POST 请求，服务器会根据请求头中的 X-HTTP-Method-Override 字段来判断请求的真实方法。

POST /zoos/1 HTTP/1.1
X-HTTP-Method-Override: DELETE