REST API接口介绍
1.概述

REST即表述性状态传递(英文:Representational State Transfer,简称REST)是一套新兴的WEB通讯协议,访问方式和普通的HTTP类似,平台接口分GET和POST两种请求方式。

玖云平台REST接口为第三方应用提供了简单易用的API调用服务,第三方开发者可以快速、高效、低成本的集成玖云平台API,轻松体验其强大的通信能力。

玖云平台的REST接口支持JSON及XML两种请求格式,采用MD5加密算法,通过URL形式发送参数。

REST接口示例代码(即Demo)下载

2.名词解释

(1).accountSid:用户注册后,为每一个开发者分配的唯一ID;32位字符,全局唯一
(2).authToken:用户注册后,为每一个开发者分配的与accountSid对应的唯一秘钥32位字符,全局唯一
(3).appId:应用ID,创建应用时,平台分配的唯一ID;32位字符,全局唯一
(4).AS:应用服务器
(5).A路:主叫侧通话
(6).B路:被叫侧通话

3.接入流程

玖云平台接口对接流程如下:

流程图

(1).注册玖云平台账号
(2).进行开发者资质认证
开发者提交资质认证后,需要平台工作人员进行信息正确性及合法性审核,审核通过后可使用平台全部功能
查看资质认证方法查看资质认证审核标准。
(3).注册成功后,登录“用户控制中心”,进行应用创建,并配置相关参数
(4).以上准备完成后,正式开始对接玖云平台的REST接口进行测试。REST接口配合回调通知接口同时使用可以实时获取接口使用状态。
查看回调接口说明
(5).玖云平台提供多种个性化定制功能,用户可通过“用户控制中心”设置相关参数,例如铃音、号码等。该步骤也可在接口对接之前进行;号码及铃音配置后,需要平台工作人员进行信息正确性及合法性审核,审核通过可进行正常使用
查看铃音设置方法查看铃音审核标准查看号码设置方法查看号码审核标准
(6).对接完成开始正式使用,使用过程中玖云平台将持续为您提供售后服务

4.请求统一包头

所有REST接口采用统一的请求包头。具体定义如下:

Base URL

文档中所有被引用的地址都有如下Base URL:
https://api.
注意: 为了确保数据隐私,平台的REST API是通过HTTPS方式请求。

请求统一包头

业务URL格式:

Base URL与业务URL相拼接为完整请求URL

主账号鉴权:

  /{softVersion}/Accounts/{accountSid}/{Func}/{funcdes}?sig={sigParameter}

HTTP标准包头字段(必填):

  Accept:application/xml;
  Content-Type:application/xml;charset=utf-8;
  Content-Length:256;
  Authorization:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

请求包头定义
属性 类型 约束 说明
softVersion String 必选 当前版本号,使用默认值2016-01-01(暂定)
accountSid String 必选 主账户Id。由32个英文字母和阿拉伯数字组成的主账户唯一标识符
sigParameter String 必选 鉴权参数,请求URL必须带有此参数,生成规则详见下方说明
Accept String 必选 客户端响应接收数据格式:application/xml、application/json
Content-Type String 必选 类型application/xml;charset=utf-8 或者 application/json;charset=utf-8
Authorization String 必选 验证信息,生成规则详见下方说明
Func String 可选 业务功能,根据业务的需要添加
funcdes String 可选 业务操作,业务功能的各类具体操作分支

参数说明:

(1).sigParameter为REST API 鉴权参数
o URL后必须带有sig参数,例如:sig=AAABBBCCCDDDEEEFFFGGG
o 使用MD5加密(主账号Id + 主账号授权令牌 +时间戳);其中主账号Id和主账号授权令牌分别对应“用户控制中心”中accountSid和authToken
o 时间戳是当前系统时间,格式"yyyyMMddHHmmss";时间戳有效时间为24小时,如:20160316142030
o sigParameter参数需要大写
(2).Authorization是包头验证信息
o 使用Base64编码(主账户Id + 冒号 + 时间戳)
o 冒号为英文冒号
o 时间戳是当前系统时间,格式"yyyyMMddHHmmss",需与sigParameter中时间戳相同
(3).Func描述业务功能,funcdes描述业务功能的具体操作
例如:专线语音为/Calls/callback
(4).支持json及xml两种格式
(5).时间戳有效期为当前北京时间前后的12小时(共24小时),为了适应全球化用户

数据报文格式

玖云平台REST接口支持两种主流的报文格式:XML和JSON。通过请求包头的字段Content-Type及Accept,即可决定请求包体和响应包体的格式。
下方示例,表示请求类型格式是XML,要求服务器响应的包体类型也是XML:
Content-Type:application/xml;charset=utf-8;Accept:application/xml;
下方示例,表示请求类型格式是JSON,要求服务器响应类型也是JSON:
Content-Type:application/json;charset=utf-8;Accept:application/json;

1 概述

2 名词解释

3 接入流程

4 请求统一包头