1.给前端资源的时候,需要给出足够的信息让前端可以进行进一步的删改
2.若给前端的信息需要解析,且解析器有多种类别,需要给出解析器类型
若给前端可执行逻辑:Java applets、JavaScript
3.客户端给服务器的信息包括:body 查询串 请求头 URI
服务端给客户端的信息包括:body 响应码 响应头(注意:body种可能包含进一步跳转链接)
4.可以设置中间服务器,功能包括:负载均衡 共享缓存 安全策略等
5.HTTP动词:
POST GET PUT DELETE 创建 读取 更新 删除
GET:返回 xml/json 200 正确 404 不存在 400 错误请求 安全 幂等
PUT:返回 200 正确(body包含内容) 204 body不包含内容 201 创建 404 不存在 非安全 幂等
POST:返回 201 location包含位置信息 404 不存在 非安全 非幂等
DELETE:返回 200 正确 (body删除内容)204 body不包含内容 404 不存在 非安全 幂等
注意:delete若用于计数器,非幂等,建议使用post
6.URL 资源名 建议动作用HTTP动词进行区分
建议看一些网页经典API设计
读源码的时候可以使用IDEA插件进行筛选,后面写个小tip
7. 返回值
json xml(xml消耗大,在淘汰边沿,使用场景不太清楚)
8.设计URL的时候需要考虑 资源粒度和通信量的问题
9.联通性考虑(这个有歧义)
POST创建后,在头位置添加新建数据链接
获取列表后,在列表中添加每个资源的链接
分页后,添加 first last next prev链接
10.返回值的body设计
code
200 (OK) —— 通常的成功状态。表示成功的最常见代码。
201 (CREATED) ——(通过POST或PUT)创建成功。通过设置Location header来包含一个指向最新创建的资源的链接。
204 (NO CONTENT) —— 封装过的响应没有使用,或body中没有任何内容时(如DELETE),使用该状态。
304 (NOT MODIFIED) —— 用于有条件的GET调用的响应,以减少带宽的使用。 如果使用该状态,那么必须为GET调用设置Date、Content-Location和ETag headers。不包含响应体。
400 (BAD REQUEST) —— 用于执行请求时可能引起无效状态的一般错误代码。如域名无效错误、数据丢失等。
401 (UNAUTHORIZED) —— 用于缺少认证token或认证token无效的错误代码。
403 (FORBIDDEN) —— 未授权的用户执行操作,没有权限访问资源,或者由于某些原因资源不可用(如时间限制等),使用该错误码。
404 (NOT FOUND) —— 无论资源存不存在,无论是否有401、403的限制,当请求的资源找不到时,出于安全因素考虑,服务器都可以使用该错误码来掩饰。
409 (CONFLICT) —— 每当执行请求可能会引起资源冲突时使用。例如,存在重复的实体,当不支持级联删除时删除根对象。
500 (INTERNAL SERVER ERROR) —— 当服务器抛出异常时,捕捉到的一般错误。
500-599 fail 400-499 error 1xx 2xx 3xx success
status
success fail error
message
fail error 的错误信息
data
错误原因 异常名字
11.跨域 JSONP CORS 建议后者 Access-Control-Allow-Origin
12.查询、过滤、分页、排序
分页:offset limi
过滤: | ::
排序:默认升序 -负序
建议查询日期排序,因为经常发生数据变换的情况下,如果没有排序,可能发生数据重复显示
13.版本管理(最多两个版本,需要进行版本控制的情况和不需要进行版本控制的情况)
14.日期格式(body header)
15.安全
身份认证 传输安全 应用安全 网关设计
16.缓存设计