JSON API是基于HTTP POST方式访问OneClick.ai模型的接口之一。用户在OneClick.ai平台登陆后，在模型列表界面选择需要的模型，进行部署。部署之后的模型会自动产生一个API的连接（URL），比如：
/api/pipeline_ykhhjcnnsqym
API连接可以用于服务器端程序对OneClick.ai平台的访问。链接中的路径部分（oneclick.ai 之后的部分）包含每个API唯一的标识序列。任何人只要拿到这个连接就可以访问此API。服务器端并不做额外的权限检查。出于安全的考虑，API连接不应该用于浏览器的代码中直接调用。
OneClick.ai平台同时也支持以GET方式的API，另外还有form-data格式的POST API。在未来的版本中，我们会逐步淘汰对这两种API格式的支持。
JSON API支持两种模式，对POST请求格式有不同的要求：
| 类型 | 协议 | mime-type | charset |
|---|---|---|---|
| 单样本请求 | POST | application/json |
utf-8 |
| 批量、多样本请求 | POST | application/json-seq |
utf-8 |
下面我们分别讨论。
单一样本的JSON API
当API服务器收到POST请求时，服务器会检查请求的HTTP Header 中的Content-Type。如果Content-Type是application/json，这个请求便作为单一样本的JSON请求处理。
请求数据格式
HTTP Header必须包含:
Content-Type: application/json; charset=UTF-8
字符集（charset）可以省略。如果省略，实际字符集仍然必须是utf-8:
Content-Type: application/json
实际传输的内容是一个JSON对象（object）。对象的属性、属性值对对应样本的特征名与特征值。例如
{"f1": "some text", "f2": true， "f3": 2.3}
代表了如下的样本：
| f1 | f2 | f3 |
|---|---|---|
| “some text” | true | 2.3 |
样本中的每个特征对应着模型训练时提供的每个特征。所有训练时提供的特征都应该在JSON对象中出现。如果某个特征的值缺失，应使用null表示。
属性的名称不可以用@开头. @开头的属性保留用于其他用处
属性值必须是简单JSON类型，既字符串、浮点数，整数，逻辑，或者null。
使用优化模型的API时，待优化的变量不需要出现在属性中。
响应数据
正常情况下 HTTP Response Code 为200
API处理结果作为一个JSON对象返回。Response Header中会包含
Content-Type: application/json; charset=UTF-8
返回的JSON对象的具体格式取决于模型的种类。
回归分析模型的返回结果较为简单，仅包含一个属性代表预测结果
{ "@pred": 23.47}
上面的例子中回归分析模型的预测结果为23.47
二元、多元分类模型的返回结果中包含了概率最大的类别，另外还包含每个类别的概率分布。
{ "@pred": "a", "@probs": {"a": 0.73, "b": 0.27}}
多标注分类模型的返回结果中包含了概率大于50%的类别，另外还包含每个类别标注自身的概率。
{ "@pred": ["a", "b"], "@probs": {"a": 0.73, "b": 0.57, "c":0.21}}
优化模型的返回结果中包含了两部分：
1. 预测模型预测的最优结果（具体格式请参考前面讲到的这几种格式）
2. 产生这一预测结果的待优化变量的取值，具体格式如下
{ "@pred": "1", "@probs": {"1": 0.73, "0": 0.27}, "@opt":{"var1": 4.3}}
上面的例子中的模型通过改变待优化变量var1来最大化类别为1的概率。返回结果中包含了待优化变量var1的最优取值，既4.3。
错误处理
如果在数据处理过程中出现任何错误，我们返回的HTTP Response Code 会设为200以外的其他值。同时返回的json对象中会包含错误信息，例如：
{ "@error":{"code": "invalid_json", "message": ""}}
其中属性message并不是必须的。
多样本的JSON API
多样本的JSON API使用的数据传输格式是json-seq。简单地说就是，数据中的每行包含一个完整的JSON 对象。
请求数据格式
HTTP Header必须包含:
Content-Type: application/json-seq; charset=UTF-8
字符集（charset）可以省略。如果省略，实际字符集仍然必须是utf-8:
Content-Type: application/json-seq
json-object数据格式为以下形式的一个utf-8序列：
(RS json-object）*
其中RS是记录分隔符，其utf-8的编码为"\x1E"。json-object是一个合法的json字符串，可以包含RS字符以外的任何合法json字符。json-object可以包含空格符(" ")、合回符("\r")、换行符("\n")等字符。
实际使用中，一般采用每行一个json对象的形式，既
"\x1E{\"a\":1, \"b\":2}\n\x1E{\"a\":3, \"b\":4}\n"
上面的例子中包含了两个json对象。主意这里的换行符不是必须的，只是一种使用习惯。
{“a”:1, “b”:2}
{“a”:3, “b”:4}
JSON对象的属性参照单样本的API中的要求。
响应数据格式
在没有错误的情况下，API处理结果以同样的json-seq格式返回给客户端。
Response Header中会包含
Content-Type: application/json-seq; charset=UTF-8
返回结果的正文中每一条记录对应着请求中的一条记录。Http response code为200（既没有错误）时，请求中每一条记录与响应中的记录是一一对应的，并且顺序保持不便。
例如：
"\x1E{\"@pred\":1.3}\n\x1E{\"@pred\":3.4}\n"
上面的例子中包含了两个样本的处理结果
{“@pred”:1.3}
{“@pred”:3.4}
错误处理
如果模型处理过程中出现任何错误，Http response code就不会是200。这种情况下，我们仍然尽力返回每个样本的处理结果。
如果遇到的错误只影响个别的样本，返回结果仍然是json-seq格式，其中的记录和请求中的记录一一对应。只是部分记录对应的返回结果中可能包含出错信息。出错信息格式请参考单样本JSON API重定义的出错信息格式。
如果因为某些原因，API无法完成全部样本的处理，我们仍然会返回已经处理的部分样本。这种情况下，返回的记录数目可能少于请求中的记录数目。每一条返回的记录和请求中开始部分的记录仍然一一对应，顺序不变。
在某些极端情况下，API可能无法处理请求中的任何样本。比如请求中的数据格式不是有效的json-seq，API将无法正确读取样本。这种情况下，API会产生json格式（而非json-seq格式）的响应。具体格式和单样本API中定义的错误处理格式相同。