API 通行接口开发人员参考规范1.0

本规范其目的在于为不同的WEB应用按照统一的规范开发用户通行接口,以便实现不同WEB应用之间的用户数据同步。

本规范不限制WEB应用开发所使用的平台、开发语言、数据库,可以适用于任何基于B/S架构的WEB应用。只要按照本规范提供完整接口和数据处理支持的WEB应用,均可称“支持BBSXP API 1.0”。

支持本规范的所有WEB应用,其技术文档中应该提供对本规范中的元素支持程度的详细说明,以供其它WEB应用开发人员以及进行二次开发的用户参考。

目 录

一、数据格式

1.请求格式

请求包必须是一个构造良好的xml文档,以post方式由XMLHttpRequest对象发送。

为了避免不同编码下的乱码,该xml中的文本应该用DOM创建而不能用字符串形式创建。

请求中的蓝色斜体部分在实际运用时要由实际值替代。每个元素的详细定义和数据格式参考“元素列表”,直接写出元素名的元素为所有请求包都必须提供的数据。

POST HTTP/1.1
Content-Type: text/xml; charset=gb2312

<?xml version="1.0" encoding="gb2312"?>
<root>
 <appid>程序标识</appid>
 <action>操作类型</action>
 <syskey>安全码</syskey>
 <username>用户名</username>
 <可选元素列表 />
</root>

2.响应格式

响应包必须是一个构造良好的xml文档。

为了避免不同编码下的乱码,该xml中的文本应该用DOM创建而不能用字符串形式创建。

请求中的蓝色斜体部分在实际运用时要由实际值替代。每个元素的详细定义和数据格式参考“元素列表”,直接写出元素名的元素为所有请求包都必须提供的数据。

当操作状态为失败时,必须提供具体的错误说明。其它情况下,根据具体的操作类型和定义决定body及其子元素。

HTTP/1.1 200 OK
Content-Type: text/xml; charset=gb2312
Content-Length: length

<?xml version="1.0" encoding="gb2312"?>
<root>
 <appid>程序标识</appid>
 <status>操作结果</status>
 <body>
    <message>操作不成功时的错误说明</message>
 <可选元素列表 />
 </body>
</root>

二、元素定义

1.元素对照表

类别 元素名称 数据格式 可选值 使用方式 备注












root -- -- 通用 根元素
appid string bbsxp
oblog
other
通用 程序标识
action string checkname
reguser
login
update
delete
请求包 操作类型
syskey string 接口安全码 请求包 安全校验码
status integer 0=操作完成
1=操作失败
返回包 操作结果
body string|
nodelist
-- 返回包 响应信息或数据
message string -- 返回包 操作失败时返回
说明信息。
username string -- 请求包 用户名
password string -- 请求包 用户密码
(未加密)
email string -- 通用 电子邮件
question string -- 通用 密码提示问题
answer string -- 通用 密码提示答案
(未加密)
savecookie string 0=不记录(默认)
1=一周
2=一月
3=一年
通用 cookies保存时间










birthday date -- 通用 生日
qq integer -- 通用 QQ帐号
msn string -- 通用 MSN帐号
address string -- 通用 通讯地址
homepage string -- 通用 个人主页
userip string -- 通用 用户IP地址






jointime datatime -- 通用 注册日期
experience integer -- 通用 经验值
posts integer -- 通用 发表信息数
userstatus integer 0=正等待审核
1=已通过审核
2=已禁用
3=未通过审核
通用 用户状态

2. 元素使用说明

本规范定义的元素共分为三组,其中第一组为实现整合通行所有程序必须支持的元素,第二、三组为各程序开发人员根据自己的情况可以自行决定是否支持的元素。

第二三组元素的主要作用在于方便利用整合接口进行跨程序的扩展功能开发。

整合接口提供的各种操作可以提供或者不提供这两组元素,由开发人员自决,

3. 接口安全码

接口安全码“syskey”是用来检验程序间传输的数据来源合法性的依据。syskey元素是一个文本元素,值为一个定长16字节的字符串。该字符串由当前传输中包含的用户名和各程序接口配置文件中用户定义的密钥(APISafeKey)连接起来,再进行16位MD5加密得出。如:
 

Set APIObject = New BBSXPAPI
APIObject.AppendNode "action","login",0,False
APIObject.AppendNode "username",UserName,1,False
SafeKey= LCase(Mid(Md5(ApiObject.XmlNode("username")&APISafeKey),9,16))
APIObject.AppendNode "syskey",SafeKey,0,False

三、操作类型说明

以下部分对action元素的各项值对应的操作做出统一规定,格式为:

操作类型(必须元素1,必须元素2...)

每个操作的定义之后,对该操作所实现的功能和返回值做具体说明。其中appid、syskey、username为所有请求操作必须提供的参数,在定义中予以省略。返回操作中的xml均不包含syskey、username两个元素。

返回值中status不等于0的,返回值必须包括body元素及其子元素messenge。

1.检查用户名、邮箱是否可以注册

定义:CheckUser()

作用:对请求中提供的用户名及email进行验证,检查是否符合注册要求。

2.注册用户

定义:AddUser(password,email)

作用:利用请求中提供的用户信息,进行用户注册。

3. 用户登录

定义:Login(password)

作用:利用请求中提供的用户名、密码和cookies选项(默认为0,不保存)为用户登录。

4. 更新用户资料

定义:EditUser()

作用:利用请求中提供的信息来更新用户资料。

5. 删除用户

定义:DelUser()

作用:根据请求中提供的用户名,对用户进行删除:

<username>用户名</username>

四、COOKIE同步操作说明

为了解决跨站同步登陆,接收请求的检验方在响应请求的接口文件中,必须增加处理Cookie的逻辑,当检测到QueryString中包含数据时,说明是对Cookies操作的请求,要完成下列工作:

1.从Request.QueryString中提取四个参数:syskey,username,password,savecookie;

2.利用username和syskey,进行安全码验证,验证成功,则利用username和password,根据savecookie的值,处理本地cookie,使指定用户处于登陆状态。

3.完成,无需返回任何信息。

发送请求方解析检验方返回的xml数据说明可以登陆成功时,则应当构造一个script脚本调用,输出到页面的HTML代码。 当password为空表示注销COOKIE信息

该脚本的路径为:

接口文件URL?syskey=16位安全码&username=用户名&password=MD5加密的16位用户密码&savecookie=Cookie保存选项