团队RESTful 风格API规范

实际上就是用RESTful风格来包装HTTP协议，并用json或xml格式实现数据交互。

RESTful风格: 网络资源实体化，CURD对资源进行操作。

好的规范评判标准：直观、扩展、优雅

1.数据交互格式

推荐json, 紧凑、易于读写、占用带宽小、各种编程语言支持。以下均已json格式为例。

HTTP 请求头:

## 客户端接受数据类型，服务端根据Accept字段调整返回消息的数据格式
Accept:application/json; charset=UTF-8 # >>>推荐
# 或  :application/xml; charset=UTF-8  # xml
# 或  :application/json,application/xml; charset=UTF-8 # xml或者json## 客户端发送数据类型
Content-Type:application/json; charset=UTF-8  # >>>推荐
# 或        :application/x-www-form-urlencoded; charset=UTF-8  # 不推荐
# 或        :multipart/form-data; charset=UTF-8  # >>>推荐用于上传文件
# 或        :application/xml; charset=UTF-8  # xml

HTTP 消息头:

## 服务端端返回消息数据类型
Content-Type:application/json; charset=UTF-8  # >>>推荐
# 或        :application/xml; charset=UTF-8   # xml

2.授权认证

由于HTTP是无状态协议，所以客户端需要携带一串经过加密的不易重复的密码串来追踪用户。web中的session机制，OAuth2.0中的tooken。比如：md5 36^32=6.3＋E49 100亿用户重复的概率是亿亿亿亿分之一

2.1 针对web客户端设计

由于web应用开发已经有成熟的用户追踪解决方案，即Session-Cookie，API设计可以延用这一方案。当客户端请求Session不存在或过期的时候，接口返回响应错误码要求用户登陆；客户端登陆成功后把session ID和其他用户信息放在Cookie里，客户端再次请求时携带该信息。

HTTP 消息头:

Cookie:sessionId=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin;  # "sessionId"键名可以由服务端自定义

HTTP 请求头:

Cookie:sessionId=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin;  # "sessionId"键名可以由服务端自定义

2.2 针对纯API客户端设计

客户端不是浏览器时或客户端不支持Cookie时，另起一个头字段“User”，当然可以是其他字段甚至可以是“Cookie”，纯粹习惯问题。客户端获取数居前需要解析下这个请求头字段（浏览器会自动解析Cookie字段）。

HTTP 消息头:

User:token=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin;  # "token"键名可以由服务端自定义

HTTP 请求头:

User:token=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin;  # "token"键名可以由服务端自定义

2.3 通用型

如果以上2.1和2.2两种情况都用“Cookie”头字段，省事了没有这一步；2.2用“User”的话就需要做个判断处理。

2.4 个人推荐

User:tooken=39rkgbkm2qqt0k9d9qmnr68difn9bs9q;userId=1;userRole=admin;

3.API命名

API指的是服务端的资源实体，它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。所以API名称一定是名称，通常以复数居多，对应数据库中的一张表，比如“users、goods、orders”。“转账”就可以当作一种服务: GET http://.../transfer?from=a&to=b&amount=100。

递进从属关系表达,如：http://.../orders/1/goods/1,表示订单ID为1的订单下面商品ID为1的商品。

3.请求

一次请求就是对服务的资源的一次操作，操作即增、删、改、查，对应HTTP四种请求方法：GET(查)、POST(增)、PUT(改)、DELETE(删)。
另有PATCH(打补丁)方法，指局部跟新，PUT指全量更新；但一般PUT当全量更新用，而PATCH方法不用。
还有OPTIONS方法，是对该接口参数和功能的说明，类似于命令行中的"--help",建议使用。

## 建议在消息头说明
Allow:GET, POST, PUT, DELETE, OPTIONS

3.1 CURD举例

GET    http://.../goods     # 列表     ?page=1&page_size=10&order_by=price&desc=1&filters={"price":{"min":10,"max":20}}
GET    http://.../goods/1   # 详情
POST   http://.../goods     # 新增     -d '{"name":"番茄","price":"3.00"}'
POST   http://.../goods     # 批量新增 -d '[{"name":"番茄","price":"3.00"}, ...]'
PUT    http://.../goods/1   # 更新     -d '{"name":"番茄","price":"3.50"}'
PUT    http://.../goods     # 批量更新 -d '[{"id":1,name":"番茄","price":"3.00"}, ...]'
DELETE http://.../goods/1   # 删除
DELETE http://.../goods/1,2 # 批量删除

3.2 辅助参数

某种特殊情况下，需要对接口行为作出调节，需要客户端额外的传参；为了防止冲突，这种参数通常以"_"开头。比如深度链接唤起应用、分享链接

# 模拟请求方法
_method=GET/POST/PUT/DELETE# 标记码
_token=39rkgbkm2qqt0k9d9qmnr68difn9bs9q# 防止跨域攻击标记码
_CSRF_token=39rkgbkm2qqt0k9d9qmnr68difn9bs9q# 格式化输出
_format=json

4.消息体

标准的消息体由三个部分组成：

{"code":200,       // 状态码，参考http状态码，建议二者保持一致, 见[6.错误码]"msg":"SUCCESS",  // 简短消息，可供客户端直接打印输出"data":{},        // 数据包
}

4.1 列表

GET http://.../goods{"code":200,"msg":"SUCCESS","data":{"list":[{...}, {...}],"count":12,"page":1,"page_size":10},
}

4.2 详情

GET http://.../goods/1{"code":200,"msg":"SUCCESS","data":{"detail":{"name":"番茄","price":"3.50"},"comments":[{"rank:5, "content":"五星好评"},{...}]},
}

4.3 POST或PUT验证失败

POST http://.../goods -d '{"name":"番茄","price":"3.50"}'{"code":406,"msg":"验证失败, 请检查是否按要求提交数据","data":{"raw":{"name":"番茄","price":"3.50元"},  // 建议返回客户端"errors":[{"price":["请输入数字类型"]}]},
}

5.文件上传与下载

上传文件 HTTP 请求头:

Content-Type:multipart/form-data

下载文件 HTTP 请求头:

Content-Type:参见http://www.runoob.com/http/http-content-type.html

6.错误码

200 OK                      # 成功处理
400 Bad Request             # 客户端请求有语法错误，例如Content-Type与请求体不符或请求体无法解析
401 Unauthorized            # 请求未经授权，例如需要登陆
403 Forbidden               # 禁止操作该资源，例如权限不够等
404 Not Found               # 请求资源不存在
405 Method Not Allowed      # 方法未允许
406 Not Acceptable          # 不可接受，未通过验证，不符合要求
408 Request Timeout         # 请求超时
500 Internal Server Error   # 服务器发生不可预期的错误
503 Server Unavailable      # 服务器当前不可用，一段时间后可能恢复正常，例如并发问题

团队RESTful 风格API规范相关推荐

RESTful风格API详解
在学习RESTful 风格接口之前,即使你不知道它是什么,但你肯定会好奇它能解决什么问题?有什么应用场景?听完下面描述我想你就会明白: 在互联网并没有完全流行的初期,移动端也没有那么盛行,页面请求和并 ...
SpringBoot RESTful 风格 API 多语言国际化i18n解决方案
文章目录 1 摘要 2 核心代码 2.1 多语言枚举类 2.2 多语言处理工具类 2.3 多语言的API返回状态码枚举类 2.4 多语言 API 接口返回结果封装 2.5 i18n 国际化多语言配置文 ...
java restful接口开发实例_实战：基于Spring Boot快速开发RESTful风格API接口
写在前面的话这篇文章计划是在过年期间完成的,示例代码都写好了,结果亲戚来我家做客,文章没来得及写.已经很久没有更新文章了,小伙伴们,有没有想我啊.言归正传,下面开始,今天的话题. 目标写一套符合规 ...
通俗易懂RESTful，如何设计RESTful风格API
REST – REpresentational State Transfer 直译:表现层状态转移.这个中文直译经常出现在很多文章中.尼玛,谁听得懂"表现层状态转移",这是人话吗? ...
如何设计RESTful风格API
REST -- REpresentational State Transfer 直译:表现层状态转移.这个中文直译经常出现在很多文章中.尼玛,谁听得懂"表现层状态转移",这是人话吗 ...
SpringBoot2.1.5(39)--- 开发restful 风格Api
SpringBoot 实现RestFul 相关注解的介绍如果说你会使用SpringMVC 那么下面的内容你阅读将会很轻松,我这里通过搭建一个用户管理接口API 让你快速学会如何创建restful ...
SpringBoot RestFul风格API接口开发
本文介绍在使用springBoot如何进行Restful Api接口的开发及相关注解已经参数传递如何处理. 一.概念: REST全称是Representational State Transfer,中 ...
HTTP的REST服务-RESTful风格API
Rest关键词解释 REST概念 REST遇到的问题及示例总结一. Rest关键词解释 REST(Representational State Transfer):表述性状态转移 Rest是web ...
深入理解幂等性及Restful风格API的幂等性问题详解
什么是幂等性 HTTP/1.1中对幂等性的定义是:一次和多次请求某一个资源对于资源本身应该具有同样的结果(网络超时等问题除外).也就是说,其任意多次执行对资源本身所产生的影响均与一次执行的影响相同. ...

团队RESTful 风格API规范

1.数据交互格式

2.授权认证

2.1 针对web客户端设计

2.2 针对纯API客户端设计

2.3 通用型

2.4 个人推荐

3.API命名

3.请求

3.1 CURD举例

3.2 辅助参数

4.消息体

4.1 列表

4.2 详情

4.3 POST或PUT验证失败

5.文件上传与下载

6.错误码

团队RESTful 风格API规范相关推荐

最新文章

热门文章