人人网开放平台技术架构
本文档介绍了人人网开放平台技术架构的设计细节和接口定义，是一个大而全的文档，涵盖了人人网开放平台对外提供的所有接口。如果你想了解人人网开放平台的整体架构和原理，或者想查阅某个接口参数，那么你一定可以在这里找到答案。
人人网开放平台的技术架构，正处于巨大的变革之中，正向着越来越标准化和通用化的方向发展。但是，为了保证兼容和过渡，我们将在比较长的一段时间之内仍然按照旧的平台架构提供之前的功能。将功能从旧的平台架构向新的人人网开放平台技术架构进行迁移将持续进行，这需要平台方和第三方共同努力。为了描述清楚，在文档中涉及到一些新老接口的过渡情况，将会详细标明。
清晰分层的技术架构
新的人人网开放平台技术架构遵循一个清晰的分层模型，架构图如下所示：
在上图所示的分层架构中，人人网开放平台提供了不同层次的功能。图中红色部分表示目前还没有提供的功能模块，需要未来由平台或开源社区来提供；黄色部分表示在旧的平台架构中已经提供但正在往新的架构中迁移的功能模块；其它颜色的是功能比较完整的功能模块。
从图中可以看出，人人网开放平台大概分为三个层次，共同为最上层的各种形式的第三方应用程序提供服务：
- Core Service Layer： 实现了人人网对外提供的最底层的API，定义好了接口参数和调用流程，第三方或平台方可以根据这个层次的API在上面封装SDK。
- SDK layer： 由第三方或平台方提供的针对各种开发语言或开发环境的SDK。
- High SDK layer： 构建在Core Service Layer或SDK Layer之上的高级SDK，例如Discuz SDK就是基于JS SDK来封装的。
第三方应用程序可以使用任意三个层次提供的API进行开发。
那么，我们为什么要推出这样的分层架构呢？因为它具有如下好处：
- 通用性。更好地支持web、mobile、desktop等运行环境，提供了多种形式的API。即提供了需要授权才能使用的Rest API，也包括无需授权即可使用的Widget API。
- 标准化。新的架构的一个很重要的特点就在于它的分层架构和明确定义的API接口，这有利于第三方获得稳定清晰的编程环境。
- 行业分工的清晰化。标准化带来的好处之一，是可以将SDK的开发维护工作交给第三方开源社区来完成，而不是全部由平台来完成。开源社区在Core Service Layer层次提供的API上开发SDK，第三方应用开发者在SDK基础上开发应用。
- 易维护和易理解。清晰的分层模型和明确定义的接口规范有利于降低平台方的维护成本，也有利于第三方对平台架构的理解。
- 扩大开放范围，提供更多新特性。在某些出于安全考虑而无法通过Rest API开放的功能，如加好友功能，则可以由新的Widget API来提供。
下面通过归类的方式详细介绍人人网开放平台技术架构的所有细节。
Auth API
第三方如果想调用人人网提供的Rest API，则必须首先经过用户授权。Auth API就是用来完成用户授权的。
目前，人人网开放平台进行用户授权遵循业界最新的标准OAuth 2.0，详情请参考：用户验证与授权。
Rest API
Rest API是人人网开放平台提供的一种使用HTTP协议来调用的API，需要在完成用户授权后才能调用。
各个Rest API的接口参数定义详见Rest API。
Widget API
Widget API是人人网开放平台提供的一种在用户控制下访问用户资源的一种API，由于是在用户控制下完成的，所以无需进行用户授权（但用户身份验证还是必需的）。这种API能够支持各种不同的运行环境，如web、mobile、桌面编程环境等等。
一个Widget可有拥有多种视图，每一种视图能够适应某个特定的运行环境。Widget可以在web浏览器中运行，或嵌入到一个原生程序（Native Application）中，或嵌入到一个对话框中。
根据通常的用途，Widget大致可以分为两类：Dialog和Plug-in。
Dialog
Dialog通常被用于弹出窗口或弹出对话框。一般在默认情况下，一个Dialog不会在第三方应用中显示出来，而是由某个用户动作触发弹出。
通常Dialog具有比较简单的用户界面。
下面是Dialog列表：
Feed Dialog
Feed Dialog提供的功能是通过弹框等方式在用户确认后发送新鲜事到人人网。可以支持web/wap网页（web/wap网站以及站内应用）、移动客户端、桌面客户端等多种运行环境。
新版Feed Dialog的优点：
- 不再依赖新鲜事模板
- 不再依赖用户授权（旧版的自定义新鲜事需要用户授权才能使用，是一个错误的流程）
- 对更多终端显示的支持
Request Dialog
Request Dialog提供的功能是通过弹框等方式在用户确认后给好友发送应用邀请或礼物，支持“一对一”或“一对多”两种方式。可以支持web/wap网页（web/wap网站以及站内应用）、移动客户端、桌面客户端等多种运行环境。
Plug-in
Plug-in通常在第三方应用中被用做一个嵌入的模块或Box，默认显示。
通常Plug-in具有比较复杂的用户界面，功能也比较丰富。
注意：上面描述的Dialog和Plug-in之间的区别并不是严格的技术上的区别，而只是用法上的区别。实际在技术上，两者的用法可以互换。例如，通过用户的触发再弹出一个窗口来显示Plug-in也是可行的。
下面是Plug-in列表：
人人喜欢
用户在第三方应用看到喜欢的内容可以点击“喜欢按钮”，同时将内容发送到人人网新鲜事。如果内容有对应公共主页，用户同时可以成为该公共主页的粉丝，接受到来自该主页的最新动态。
技术文档详见like，一个web配置和预览界面：web喜欢按钮的配置。
Like Box（新版还未上线）
Like Box是一个为公共主页拥有者提供的社会化插件。公共主页拥有者可直接将此box嵌入自己的应用（目前只支持web网站和web站内应用），用户可在第三方网站上点击喜欢成为该主页粉丝，并浏览该主页新鲜事及现有的关注者。
在新版Like Box上线之前，可以使用旧的粉丝小部件：技术文档参见粉丝小部件，配置和预览界面参见粉丝小部件的配置。
新版Like Box的优点：
- 支持新鲜事浏览
- 不再依赖appId（旧的粉丝小部件错误地依赖appId参数，导致只能为应用的公共主页创建粉丝小部件），从而可以用于人人网任何公共主页
Comment Box
Comments Box是一个社会化插件，便于人人网用户在第三方应用（目前只支持web网站和web站内应用）中发表评论。 相关文档地址。
Live Stream Box
可以让用户在第三方应用（目前只支持web网站和web站内应用）中针对某一热点话题进行实时讨论，用户的评论以人人网状态的形式发送到人人网主页。
技术文档：xn:live-stream；配置和预览界面：Live Stream Box配置
好友派
在第三方应用（目前只支持web网站和web站内应用）中显示好友头像列表的社会化插件，与好友进行交互，增强社交属性。
技术文档：xn:friendpile；配置和预览界面：好友派配置
Callback API
Iframe callback
Iframe callback用于第三方开发Web站内应用，在Canvas页（即http://apps.renren.com/yourapp）与人人网深入整合。
Iframe类型的应用的接入方式，是在Canvas页（即http://apps.renren.com/yourapp）通过iframe嵌入一个第三方的页面，在iframe的src中传递一些xn_sig_xxx参数给第三方服务器。第三方服务器解析和验证这些参数，取得用户的标识（如uid, session key等），然后用session key去调用Rest API，获取用户更多信息，从而产生一个动态页面。
xn_sig_xxx参数的相关信息（包括如何校验这些参数）请参见关于xn_sig参数。
XNML callback
XNML callback用于第三方开发Web站内应用或Wap站内应用，在Canvas页（即http://apps.renren.com/yourapp 或 http://mapps.renren.com/yourapp）与人人网深入整合。
XNML类型的应用的接入方式，是当用户访问在Canvas页（即http://apps.renren.com/yourapp 或 http://mapps.renren.com/yourapp）时，由平台服务器代理用户的请求，平台服务器向第三方服务器发送POST请求。在这个POST请求中，传递一些xn_sig_xxx参数给第三方服务器。第三方服务器解析和验证这些参数，取得用户的标识（如uid, session key等），然后用session key去调用Rest API，获取用户更多信息，从而产生一个动态页面。由于安全原因，这个动态页面不能是普通的HTML页面，只能使用由人人网开放平台定义的XNML代码来组装页面，返回给平台服务器。最后平台服务器将XNML代码解析渲染成普通的HTML代码，返回给浏览器。
xn_sig_xxx参数的相关信息（包括如何校验这些参数）请参见关于xn_sig参数。
在第三方服务器返回平台服务器响应时，可以分别使用下列三个技术来书写标签、CSS和JavaScript：
Real-Time API
Real-Time API是一种高级的API形式，使用方式是：第三方应用可以订阅用户在人人网的一些信息变化（如收到提醒、好友关系变化、个人信息变化等），由人人网服务器在订阅信息发生变化时主动将消息推送给第三方，从而可以完成一些实时消息提醒之类的高级功能。详见Real time api
各种SDK
SDK一部分由人人网开放平台官方提供，一部分由开源社区提供。以开源代码的方法是进行维护。
目前提供的SDK请参阅SDK。
开放平台领域的社会化分工
新的经过清晰分层的人人网开放平台技术架构，有利于促进开放平台领域的社会化分工。
在之前，第三方应用开发者所使用的所有API，大部分都由开放平台官方提供，包括各种开发SDK。而经过架构分层，底层的Core Service Layer提供的API被清晰地定义，就可以将底层接口的开发和SDK的开发明确的区分开来。这样带来的好处是：开放平台集中精力提供底层的接口，致力于增加接口种类，而上层的SDK封装工作可以由第三方开发者自己或开源社区来进行。
为了促进开放平台领域的发展，人人网开放平台倡导开源精神，集中开源社区的力量，对有利于第三方开发者进行开发或接入的代码进行开源管理。这这些开源的代码一部分由人人网开放平台官方开发出初始版本，然后发布为开源的license，由开源社区来管理；另一部分直接由开源社区来贡献。
欢迎加入人人网开源项目！
