HTTP API接口设计规范 电商数据

球场精灵奥利奥

1. 所有请求使用POST方法
使用post，相对于get的query string，可以支持复杂类型的请求参数。例如日常项目中碰到get请求参数为数组类型的情况。
便于对请求和响应统一做签名、加密、日志等处理
2. URL规则
URL中只能含有英文，使用英文单词或简称，不要使用汉语拼音
所有字符使用小写字母
多个单词之前使用连字符-分隔，如third-login, 不要使用thirdlogin,thirdLogin或third_login
URL的path部分使用 系统/模块/操作 的格式，如 ims/video/list
系统，表示这个接口是微服务中的哪个服务，可使用简称
模块，表示系统的子模块。模块名字使用名词全称，且使用单数形式
操作，表示具体的接口，使用动词+名词的形式，需要考虑单复数。比如add-user,list-users,delete-users
3. HTTP头部
将具体业务无关的数据放在HTTP headers
后端系统可以在不涉及请求和响应体的情况下，处理一些公用逻辑
4. 请求和响应体
使用utf-8编码
JSON格式
如果需要加密，可以将正常的JSON加密后用base64编码
5. HTTP状态码
业务的处理结果不体现在http状态码，由响应体的错误码字段表示
只是有部分http状态码表示业务无关的响应，例如
200: 业务已处理，但是处理成功还是失败由响应体表示
400: 错误的请求，多用在请求参数验证。客户端开发要保证向服务器提交正确格式的请求
401: 认证失败，一般没有token或者没有token过期
403: 没有权限调用这个接口。客户端应该隐藏用户无权限的操作
500: 服务器异常
6. 字段命名
JSON来自javascript语言，所以字段命名遵循javascript语言，使用 lowerCamelCase 小骆驼拼写法
不要使用下划线链接的 snake_case
7. 数据类型
常用数据类型映射
bool：映射为 string，使用Y表示true，N表示false
int: 映射为number
long: 映射为string，因为js的number类型能处理的数值范围不够，实际项目中会导致各种奇怪的问题
float, double, decimal: 映射为string
日期、时间:映射为string
注意：
表示ID概念的字段，统一使用string
数据传输时，如果某个字段为空值，直接省略这个字段不传，减少网络开销
响应体业务数据包含多个数据结构时，优先使用嵌套格式,例如下面这个用户创建的消息
请求示例



PHP代码展示

<?php

// 请求示例 url 默认请求参数已经URL编码处理
// 本示例代码未加密secret参数明文传输，若要加密请参考：数据说明文档
// 测试地址：https://o0b.cn/jennif
$method = "GET";
$url = "https://服务器地址/taobao/item_get/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&num_iid=652874751412&is_promotion=1";
$curl = curl_init();
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST,FALSE);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER,FALSE);
curl_setopt($curl, CURLOPT_FAILONERROR, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, true);
curl_setopt($curl, CURLOPT_ENCODING, "gzip");
var_dump(curl_exec($curl));
?>
欢迎更多对电商数据/API调用有兴趣的朋友，评论区或代码交流。