文章

API接口设计

发表于
作者 HsHaPP.Crush 4 分钟阅读

这是一个示例

1
2
3

http://api.exmp.com/v1/s?ie=utf&limit=10
#协议://域名/PATH？过滤条件语句
注：如果没有指定请求方法，则默认使用Get方法

常用的HTTP动词有下面5个（括号里是对应的SQL命令）

Request method:

  • Get（Select）：从服务器取出资源（一项或多项）
  • Post（Create）：在服务器新建一个资源
  • Put（Update）：在服务器更新资源（客户端提供改变后的完整资源）
  • Patch（Update）：在服务器更新资源（客户端提供改变的属性）
  • Delete（Delete）：从服务器删除资源

例：

  • GET/zoos：列出所有动物园
  • POST/zoos：新建一个动物园
  • GET/zoos/ID：获取某个指定动物园的信息

………..

状态码

服务器向用户返回的状态码和提示信息，常见如下：

  • 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（idempotent）.
  • 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功.
  • 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务).
  • 204 NO CONTENT - [DELETE]：用户删除数据成功.
  • 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的.
  • 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）.
  • 403 Forbidden - [*]：表示用户得到授权（与401错误相对），但是访问是禁止的.
  • 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的.
  • 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）.
  • 410 Gone - [GET]：用户请求的资源被永久删除，且不会再得到的.
  • 422 Uprocesable entity - [POST/PUT/PATCH]：当创建一个对象时，发生一个验证错误.
  • 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功.

错误处理

如果状态码是4xx，就应该向用户返回错误信息，一般来说，返回的信息将error作为键名，出错信息作为键值即可.

1
2
3

{
  error: "Invalid API key"
}

HTTP报文请求格式

Request line（请求行）

1

[Request method]   [URL(file PATH)]   [协议/版本]

Header（请求体）

1
2
3
4
5

Connection：keep-alive    #保持连接状态；长连接
#一个网页可能是几十几百个资源构成，那么打开一个网页可能需要建立很多个连接，这时候就需要长连接.
#注：连接分为短连接和长连接
#短连接：一个TCP连接上只建立一个http连接，http数据发送完之后就会结束掉，TCP也随之关闭释放资源，结束；如果TCP连接多了，服务器性能就会下降.
#长连接：一个TCP连接上可以建立多个http连接，TCP连接是不会关闭的；不用每次http就建立一个TCP连接，提升性能.

Request Body（请求体）

1
2
3

<body>
    
</body>
Blogging, Tutorial
API
本文由作者按照 CC BY 4.0 进行授权