API分类
API
:
分类1:A程序需要B程序的部分功能,只需要将B程序部分功能打包直接给A程序使用。比如:Java jar。这种API称之为SDK。
分类2:A程序需要B程序部分功能,B程序提供对外访问路径,A程序按照约定的访问路径访问即可。比如:具有http协议请求访问。这种API称之为Web应用接口。
HTTP响应状态码
状态码 | 状态 |
---|---|
200 OK - [GET] | 服务器成功返回用户请求的数据 |
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 Unprocesable entity - [POST/PUT/PATCH] | 当创建一个对象时,发生一个验证错误 |
500 INTERNAL SERVER ERROR - [*] | 服务器发生错误,用户将无法判断发出的请求是否成功 |
资源表示形式
比如:文本可以用txt格式来表示,也可以用HTML格式、XML格式、JSON格式甚至可以采用二进制格式来表示;图片和音频也是一样,有多种格式可以表示它们。
它们的具体表现形式,应该在HTTP请求头中用
Accept
和Content-Type
字段来指定,这两个字段是对"表现"的描述:
RESTful接口设计
背景
:
不同开发者对于API接口的设计习惯不同,因此需要一个统一的,科学的API接口。
RESTful风格
:
REST是一种设计API接口的规范,或者说风格,简单易懂,容易使用。在设计接口时,如果满足rest约束条件和原则的应用程序或设计就称之为RESTful应用。
约束规则
:
请求路径:以操作的资源决定,一般采用资源(实体)名称的复数形式。比如/employees
请求方式:
请求方式 | 说明 |
---|---|
GET (SELECT) | 从服务器取出资源(一项或多项) |
POST (CREATE) | 在服务器新建一个资源 |
PUT (UPDATE) | 在服务器更新资源(客户端提供改变后的完整信息)。PUT更新整个对象 |
PATCH (UPDATE) | 在服务器更新资源(客户端提供改变的属性【补丁】)。PUT更新整个对象 |
DELETE (DELETE) | 从服务器删除资源 |
请求参数:由需求决定。
请求响应:一般都使用JSON格式。
请求方式 | 说明 |
---|---|
GET / collection | 返回资源对象的列表(数组) |
GET / collection / resource | 返回单个资源对象 |
POST / collection | 返回新生成的资源对象 |
PUT / collection / resource | 返回完整的资源对象 |
PATCH / collection / resource | 返回完整的资源对象 |
DELETE / collection / resource | 返回一个空文档 |
RESTful 风格只是一种开发规范的建议,并不是强制约束。实际以开发要求为准。