编辑“预订宝/API总体架构”

{{预订宝导航}}
==通讯协议==
预订宝开放平台的[[API]]完全基于HTTP协议实现，为了降低接入难度，仅使用了[[HTTP]]协议中的[[GET]]和[[POST]]两种方式通讯，而不是完全的RESTful方案。

API接口的唯一域名是<nowiki>http://api.yudingbao.net/</nowiki>，下面是关于接口地址的一些约定：
#接入地址形如：<nowiki>http://api.yudingbao.net/v1.0/generictools/ipsearcher.ashx</nowiki>；其中“v1.0”表示API版本号，而后的“generictools/ipsearcher.ashx”等是具体的子模块及处理程序地址；
#每个子模块对应一个独立的地址，通过QueryString或Form参数来实现一种或多种功能；

'''特别说明：'''
开放平台所包含的日期时间均为[[UTC]]格式，解析时请自行处理时区转换。

==鉴权方式==
预订宝开放平台采用统一的密钥标记鉴权，这是一种非常轻量级的鉴权方式，非常容易掌握和使用。

在某些情况下，密钥标记鉴权无法保证API调用者的数据安全，因此一些特殊的需求请遵循相关子模块定义的鉴权机制（比如提交订单、修改订单等）。

==平台适用性==
预订宝开放平台完全基于标准的HTTP协议，因此它是完全跨平台的，并且，我们针对不同的平台应用方案做了一些优化，这能让更加方便的使用API。

API支持[[Json]]、[[JsonP]]、[[Xml]]、[[Html]]、[[Text]]和[[Binary]]六种响应模式，实际上只有Json、JsonP和Xml最为常用。每个API接口都可能不完全实现如上6种响应模式，具体请参考API接口概述中的响应模式一栏，指定了不受支持的响应模式会引发异常！

此外，API具有字符编码自适应的能力，方便对接而不需要执行任何编码转换。

==通用选项==
尽管开放平台中的每一个产品头附带了较为详细的使用说明，然而在那些文档里却不会提到以下这些通用选项。

但请注意，以下这些选项是最基础的、最通用的，关注并掌握这些参数的使用，能够让开发效率大大提升！
{|border="1" align="center" width="75%"
|-
!参数名称|| 参数类型|| 取值说明|| 参数功能
|-
| aid
| string
| 纯数字格式的字符串
| 产品编号。在分销产品的应用列表中可以找到该参数的值。
|-
| key
| string
| 仅字母和数字
| 接口密钥。在分销产品的应用列表中可以找到该参数的值。
|-
| sid
| string
| 仅字母和数字
| 应用程序标识符，仅针对开发者发放。
|-
| skey
| string
| 仅字母和数字
| 应用程序公钥，仅针对开发者发放。
|-
| act
| string
| 仅字母和数字
| 动作标识。在每个子模块中指示在该接口上应当执行如何的操作。
|-
| rowspan="6" | format
| rowspan="6" | string
| 枚举值：json
| 指定响应格式为Json，此时会将Content-Type设置为“application/json”。
|-
| 枚举值：jsonp
| 指定响应格式为JsonP，此时会将Content-Type设置为“text/javascript”。
|-
| 枚举值：xml
| 指定响应格式为Xml，此时会将Content-Type设置为“text/xml”。
|-
| 枚举值：html
| 指定响应格式为Html，此时会将Content-Type设置为“text/html”。
|-
| 枚举值：text
| 指定响应格式为纯文本，此时会将Content-Type设置为“text/plain”。
|-
| 枚举值：binary
| 指定响应格式为二进制，此时会将Content-Type设置为“application/octet-stream”。
|-
| rowspan="2" | encoding
| rowspan="2" | string
| rowspan="2" | utf-8、GB2132、936等
| 指定字符编码。如指定了非法编码名称，则以UTF-8替代。
|-
| 点击此处查看所有受支持的字符编码的列表
|-
| indent
| bool
| [true|false]
| 当输出格式为JSON、JSONP或XML时，该参数指示是否对输出结果执行格式化。
|-
| rowspan="2" | indentChar
| rowspan="2" | char
| align="right" | 0
| 当输出格式为JSON、JSONP或XML时，该参数设置缩进字符为空格。
|-
| 1（默认值）
| 当输出格式为JSON、JSONP或XML时，该参数设置缩进字符为TAB字符。
|-
| indentation
| int
| [0, 8]
| 当输出格式为JSON、JSONP或XML时，该参数设置缩进级别，默认为1，最大为8.
|-
| rowspan="8" | jsonmode
| rowspan="8" | string
| rowspan="2" | 枚举值：default
| 当输出格式为JSON、JSONP时，不对输出结果执行任何特定优化。
|-
| 举例：该模式下日期的输出格式为“Date(1303660800000)”；
|-
| rowspan="2" | 枚举值：strict
| 当输出格式为JSON、JSONP时，将输出结果执行严格的标准化处理。
|-
| 举例：该模式下日期的输出格式为“    Thu, 24 Apr 0042 16:00:00 GMT ”；
|-
| rowspan="2" | 枚举值：javascript
| 当输出格式为JSON、JSONP时，将输出结果针对JavaScript进行优化。
|-
| 举例：该模式下日期的输出格式为“new    Date(1303660800000)”；
|-
| rowspan="2" | 枚举值：php
| 当输出格式为JSON、JSONP时，将输出结果针对php进行优化。
|-
| 举例：该模式下日期的输出格式为“1303660800”，即以秒为单位的整型数字；
|-
| callback
| string
| 仅字母和数字，以字母开头
| 当输出格式为JSONP时指定回调方法的名称，默认值为：jsoncallback
|-
| xmlroot
| string
| 仅字母和数字，以字母开头
| 当输出格式为XML时指定XML根节点的名称，默认值为：HttpResponse
|}

'''注意：'''
#如上列表中的参数不区分HTTP通讯方式，GET或POST皆可；
#传统的[[jQuery]]、[[Mootools]]等[[javascript|js]]库都支持JsonP，然而它们都只支持GET方式，因为标准的JsonP是基于<script />标记实现的。如果需要以POST的方式访问接口，那么必须在“域”下使用[[服务器]]中继；

==参考来源==
*http://www.yudingbao.com/dev/api.html


[[category:预订宝|A]]

{{预订宝使用手册导航}}