集成指南

当前文档为千帆新版本的开放接口，基于rest规范构建，诣在提供更加开放、更加安全、更加易于调用的对外接口。旧版本接口会继续维护，但是不会再新增接口。

本接口面向千帆客户中具有开发能力的站点以及基于千帆系统开发第三方功能的平台。

点此进入>>> 旧版本接口文档 <<<。旧版接口已经不再维护，仅供历史查阅，新功能开发请采用新版接口。

REST概述

关于REST

REST（Representational State Transfer）是一种轻量级的 Web Service 架构风格，可以翻译成“表述性状态转移”，实现和操作明显比 SOAP 和 XML-RPC 更为简洁，可以完全通过 HTTP 协议实现，还可以利用缓存 Cache 来提高响应速度，性能、效率和易用性上都优于 SOAP 协议。

REST 架构遵循了 CRUD 原则，CRUD 原则对于资源只需要四种行为：Create（创建）、Read（读取）、Update（更新）和Delete（删除）就可以完成对其操作和处理。这四个操作是一种原子操作，对资源的操作包括获取、创建、修改和删除资源的操作正好对应 HTTP 协议提供的 GET、POST、PUT 和 DELETE 方法，因此 REST 把 HTTP 对一个 URL 资源的操作限制在 GET、POST、PUT 和 DELETE 这四个之内。这种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。

更多 REST API 背景知识可以参考RESTful API 设计指南

REST server

服务器端接口都是通过REST服务方式提供的，REST API基于最简单的HTTP协议。

REST client

REST client 就是调用 REST API 的程序端，调用方式有多种：Linux curl、浏览器、编程语言 HTTP 请求访问实现等。

调用 REST API，本质就是发送 HTTP 请求，只不过大家常用的可能是 HTTP GET 和 HTTP POST 请求，但是在 REST 里面还经常用到 HTTP PUT 和 HTTP DELETE。在 REST 中，把这四种操作称之为动词，可以（但不是特别准确）想象成增删改查。

而动词所操作的对象，在 REST 中，被称之为“资源”，也就是 URL，而这些也都是标准的 HTTP 协议的内容。实际上，当我们在浏览器中打开一个网站的时候，例如，打开千帆官网，浏览器实际上发送给网站服务器的，就是一个 HTTP GET 的请求。

需要注意的是，千帆的 REST API 可以是基于 JSON 的，所以允许直接提交json格式的请求体，但是需要在请求头中指定Content-Type:application/json

Content-Type： MediaType，即是Internet Media Type，互联网媒体类型；也叫做MIME类型，在Http协议消息头中，使用Content-Type来表示具体请求中的媒体类型信息。

同时千帆开放平台支持两种响应体格式的设置 json/xml。默认返回json格式的数据。如果需要xml格式，需在请求头中指定Accept:application/xml

在后面的接口文档中，我们都默认以Content-Type:application/json、Accept:application/json作为示例

举例说明

我们以解析wap_token接口为例，正常我们都需要json格式的响应，传入普通的表单请求

curl -X POST \
http://站点接口域名/openapi/user/parse-user \
-H 'Authorization: Bearer 5d39164d1f281' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json' \
-d 'wap_token=479b19h2GlL9IYfV3v1XK5HZJC1PDaNPb5t9bjqmKFbOXHWrWMyEUFQgYgwKj%2FSpcb7pKH8j4Amph52m93Ew0qq8KHteDd69O0Y0dscwmvTDPfPjp9olBx3v1hgB0K12i5PInD%2BA9grqUYjYTzSAiq6gRWt1iOO4z0GkYnCpbMFzaH5HPmjK%2BmxpfmWguj6J7YYsxrZxRDQzakkiN0OORNSkQnERnRQfViLJzJ4A'

或者使用json格式的请求体

curl -X POST \
http://站点接口域名/openapi/user/parse-user \
-H 'Authorization: Bearer 5d39164d1f281' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"wap_token":"479b19h2GlL9IYfV3v1XK5HZJC1PDaNPb5t9bjqmKFbOXHWrWMyEUFQgYgwKj%2FSpcb7pKH8j4Amph52m93Ew0qq8KHteDd69O0Y0dscwmvTDPfPjp9olBx3v1hgB0K12i5PInD%2BA9grqUYjYTzSAiq6gRWt1iOO4z0GkYnCpbMFzaH5HPmjK%2BmxpfmWguj6J7YYsxrZxRDQzakkiN0OORNSkQnERnRQfViLJzJ4A"}'

上述两种请求将产生相同的响应结果，如下所示：

{
    "code": 0,
    "text": "",
    "data": {
        "id": 1234,
        "username": "faye0017",
        "signature": "千帆最亮的仔",
        "gender": 1,
        "birthday": 631152000,
        "avatar": "http://bbs1.qianfanyun.com/uc_server/data/avatar/000/00/16/90_avatar_big.jpg",
        "phone": ""
    },
    "time": 1564987256
}

如果需要xml的响应，只需要修改Accept请求头即可：

curl -X POST \
http://站点接口域名/openapi/user/parse-user \
-H 'Authorization: Bearer 5d39164d1f281' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/xml' \
-d 'wap_token=479b19h2GlL9IYfV3v1XK5HZJC1PDaNPb5t9bjqmKFbOXHWrWMyEUFQgYgwKj%2FSpcb7pKH8j4Amph52m93Ew0qq8KHteDd69O0Y0dscwmvTDPfPjp9olBx3v1hgB0K12i5PInD%2BA9grqUYjYTzSAiq6gRWt1iOO4z0GkYnCpbMFzaH5HPmjK%2BmxpfmWguj6J7YYsxrZxRDQzakkiN0OORNSkQnERnRQfViLJzJ4A'

结果如下所示：

<?xml version="1.0" encoding="UTF-8"?>
<response><code>0</code>
    <text></text>
    <data>
        <id>1234</id>
        <username>faye0017</username>
        <signature>千帆最亮的仔</signature>
        <gender>1</gender>
        <birthday>631152000</birthday>
        <avatar>http://bbs1.qianfanyun.com/uc_server/data/avatar/000/00/16/90_avatar_big.jpg</avatar>
        <phone></phone>
    </data>
    <time>1564987999</time>
</response>

返回数据结构说明

统一的响应数据结构

{
    "code": 0,
    "text": "",
    "data": {}, // 数组或者对象
    "time": 1545720082
}

返回说明

Code 规范说明