移动端数据接口返回数据格式(上)

￡神魔★判官ぃ 2022-06-12 07:14 246阅读 0赞

### 一、接口规则： ###

<table style=""> 
 <thead style=""> 
  <tr style=""> 
   <th style="">传输方式</th> 
   <th style="">为保证交易安全性，建议采用HTTPS传输</th> 
  </tr> 
 </thead> 
 <tbody style=""> 
  <tr style=""> 
   <td style="">提交方式</td> 
   <td style="">采用HTTP协议中的方法提交</td> 
  </tr> 
  <tr style=""> 
   <td style="">数据格式</td> 
   <td style="">提交和返回数据都为json格式</td> 
  </tr> 
  <tr style=""> 
   <td style="">字符编码</td> 
   <td style="">统一采用UTF-8字符编码</td> 
  </tr> 
  <tr style=""> 
   <td style="">签名算法</td> 
   <td style="">MD5</td> 
  </tr> 
  <tr style=""> 
   <td style="">签名要求</td> 
   <td style="">请求和接收数据均需要校验签名，详细方法请参考<a href="http://docs.blogcore.cn/standard_api/chapter4/aqgf.md" style="" rel="nofollow">安全规范-签名算法</a><br> </td> 
  </tr> 
 </tbody> 
</table>

# 二、状态码规范 #

### 204 No Content ###

如果更新成功，且客户端属性保持最新，服务器必须返回204 No Content状态码。适用于PUT请求，以及仅调整links，不涉及其它属性的POST, DELETE请求

### 200 OK ###

如果服务器接受更新，但是在请求指定内容之外做了资源修改，必须响应200 OK以及更新的资源实例，像是向此URL发出GET请求.

### 201 Created ###

如果服务器需要创建一些资源, 比如创建用户, 创建用户数据, 创建资源, 默认API的create方法返回这个状态码.

### 301 Moved Permanently ###

被请求的资源已永久移动到新位置, 适用于资源link的变更,服务器做出兼容API.

### 303 See Other ###

对应当前请求的响应可以在另一个 URI 上被找到，客户端应该使用 GET 方法进行请求, 适用于旧API往新API的兼容.

### 400 Bad Request ###

请求体包含语法错误, 出现本错误服务端应该向客户端发送出错描述

适用于:

*  发送了无法转化的请求体

### 401 Unauthorized ###

需要验证用户身份，如果服务器就算是身份验证后也不允许客户访问资源，应该响应 403 Forbidden, 适用于未登录检查

### 403 Forbidden ###

服务器拒绝执行

适用于:

*  服务到期（比如付费的增值服务等）
 *  因为某些原因不允许访问（比如被 ban ）
 *  权限不够，403 状态码

### 404 Not Found ###

找不到目标资源

适用于:

*  需要修改的资源不存在

### 405 Method Not Allowed ###

不允许执行目标方法，响应中应该带有 Allow 头，内容为对该资源有效的 HTTP 方法

### 406 Not Acceptable ###

服务器不支持客户端请求的内容格式（比如客户端请求 JSON 格式的数据，但服务器只能提供 XML 格式的数据）

### 409 Conflict ###

请求操作和资源的当前状态存在冲突

### 410 Gone ###

被请求的资源已被删除

### 412 Precondition Failed ###

服务器在验证在请求的头字段中给出先决条件时，没能满足其中的一个或多个。主要使用场景在于实现并发控制

### 413 Request Entity Too Large ###

POST 或者 PUT 请求的消息实体过大

### 415 Unsupported Media Type ###

服务器不支持请求中提交的数据的格式

### 422 Unprocessable Entity ###

请求格式正确，但是由于含有语义错误，无法响应

适用于:

*  发送了非法的资源

### 428 Precondition Required ###

要求先决条件，如果想要请求能成功必须满足一些预设的条件 适用于:

*  缺少了必要的头信息

### 500 Internal Server Error ###

服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理。

### 501 Not Implemented ###

服务器不支持当前请求所需要的某个功能。 501 与 405 的区别是：405 是表示服务端不允许客户端这么做，501 是表示客户端或许可以这么做，但服务端还没有实现这个功能

### 502 Bad Gateway ###

作为网关或者代理工作的服务器尝试执行请求时，从上游服务器接收到无效的响应。

### 503 Service Unavailable ###

由于临时的服务器维护或者过载，服务器当前无法处理请求。这个状况是临时的，并且将在一段时间以后恢复。如果能够预计延迟时间，那么响应中可以包含一个 Retry-After 头用以标明这个延迟时间（内容可以为数字，单位为秒；或者是一个 HTTP 协议指定的时间格式）。如果没有给出这个 Retry-After 信息，那么客户端应当以处理 500 响应的方式处理它。

适用于: 服务器维护中

# 三、安全规范 #

### 1.签名算法 ###

签名生成的通用步骤如下：

第一步，设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。 特别注意以下重要规则：

>  *  参数名ASCII码从小到大排序（字典序）；
>  *  如果参数的值为空不参与签名；
>  *  参数名区分大小写；
>  *  验证调用返回或主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验。
>  *  接口可能增加字段，验证签名时必须支持增加的扩展字段

第二步，在stringA最后拼接上key得到stringSignTemp字符串，并对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为大写，得到sign值signValue。

举例，假设传送的参数如下：

<?php
    $id = '380840976';
    $author_id = '1000000';
    $body = 'test';
    $date = gmdate('D, d M Y H:i:s \G\M\T');

第一步：对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：

<?php
    $stringA= "id=".$id."&author_id=".$author_id."&body=".$body."&date=".$date;

第二步：拼接API密钥并进行签名：

<?php
    $stringSignTemp=$stringA."&key=302006259b3c09247ec02edaf64f6a5f";
    $sign=strtoupper(MD5($stringSignTemp));

最终得到最终发送的数据

### 2.发送请求 ###

将上一步生成的签名，放到 HTTP 消息头中。如果没有签名或者签名错误，则会导致接口调用失败，服务端会返回 HTTP 状态码 401

格式如下：

<?php
    $headers = [
            "Date: ".$date, // header 中使用的时间必须和生成签名的时间$date相同
            "Authorization: Blogchina $appid:".$sign,//$appid 为开发者申请的appid
        ];
    $body = [
        'id'=>$id,
        'author_id'=>$author_id,
        'body'=>$body,
        'date'=>$date,
    ];
    
    $response = Unirest\Request::post("http://api.blogchina.com/", $headers, $body);
    $response->raw_body;

### 3.回调API安全 ###

在普通的网络环境下，HTTP请求存在DNS劫持、运营商插入广告、数据被窃取，正常数据被修改等安全风险。用户回调接口使用HTTPS协议可以保证数据传输的安全性。所以建议用户回调采用HTTPS协议。