校内API开发简易指南

是时候研究一下国内的开放式API了，所以抽时间搞了一下，先从校内下手吧，相对来讲他的资料算是最多的了。但是即使如此，想从零开始写一个应用出来，还真是花了我不少功夫。资料实在是太难找了。校内的API从6、7月份就出来了，还弄了个专门的Wiki作为开放平台的门户，但是里面的资料出奇的少，除了对几个api函数的说明，对xnml的简单说明，其它的几乎为0。所谓的一个上手指南只讲了怎么注册用户和怎么注册程序，注册完以后的开放过程却一点也没提。想根据这份东西写个真正的应用出来，简直是不可能的任务。没办法，上Google，上社区，上应用的论坛，一篇篇帖子里找线索，最后总算是把一个应用给凑出来了。

如此糟糕的技术支持能力，直接决定了校内API应用的未来。

开发过程简介：

首先需要注册成校内用户，然后在自己的菜单上有个应用，添加一个“开发者”应用，这里面包括一个社区，一些开发所需要的链接。进入这个应用以后，可以看到一个申请开发许可证的按钮，点击就进入设置应用属性的环节，起名字，定URL之类的。（这一步在校内的Wiki上是有说明的。）有个安装到校内的选项，默认是否，结果选了以后我的应用就变成了外部应用，在校内只提供一个链接进入而已，这当然不行了。当我把应用删了重新添加的时候，原来使用的那个URL被占用了，无耐，换了个更难看的URL。应用还有一个重要的属性，就是运行状态，是以iframe形式还是xnml形式，这个待会再讲。第一次建议先选iframe形式，这个是随时可以修改的。

这些东西都设置完，应用就生成了。你会得到一个api_key，一个secret key，不过这两个东西都没什么用。

校内应用的工作原理：

如果是xnml方式的应用，用户访问apps.xiaonei.com/xxxxx/yyyyy这样一个地址的时候，xxxxx代表你申请一个应用的时候自己定义的那个URL，校内的API服务器会在后台将用户对该页面的请求（包括所有参数）转发给你的应用，也就是你申请应用的时候填的那个自己的应用地址。如果你的应用在你的服务器上是www.aaa.com/xxxxx/这样一个目录，那么上面这个请求就会被转发到www.aaa.com/xxxxx/yyyyy这里，不管yyyyy是个html页面还是个目录形式。转发的同时，还会多几个参数过来，包括当前用户的id，当前用户的sessionid，还有你的api key。你后续的所有的页面的链接，都要写成以apps.xiaonei.com开头的地址，由它来转发请求。

如果是iframe的应用就简单多了，海内直接生成一个iframe，把你注册时填的那个起始地址放进去，同时包括前面说的几个相同的参数。剩下的事情他们就不管了。

因为每次请求都是校内的服务器发给你，所以你的服务器上写Cookie或者session之类的东西是没有用的，必须每次取得这几个参数来决定当前用户是哪一个。（校内在这里有一个极其严重的设计失误，那就是没有用到创建程序时生成的那个secret key。校内发过来的这三个参数只能帮你确定是哪一个userid发过来的请求，而这三个参数之间是没有什么关联性的，比如你无法根据sessionid来判断这个userid是否合法。而在iframe状态的应用里，这三个参数直接暴露在浏览器代码里，用户只要复制下来，把userid改成另外一个数字放到浏览器地址栏里就OK了。现在，如果你想确保访问用户的合法性，就必须要通过校内的API调用，到他的服务器上去，把这三个参数发过去，看它的返回结果，多一次网络调用所带来的时间损失，远远大于任何的数据库运算或者数字运算。实际上，校内只要加上第四个参数，也就是你的secret key和其中任何一个参数合并后的md5码，你在取值以后用同样的算法生成md5码，比较一下跟传过来的值是否相等就OK了，完全不需要为了验证用户合法性而增加一次网络调用。更可恶的是，每个页面你都要做一次这样的网络调用。当然，你也可以在验证合法以后用自己的服务器保存一下userid和sessionid的对应关系，下次请求如果仍然是这两个数值就不用再网络验证了，但是这又增加了无谓的数据库调用。）

你已经拿到了用户在校内上的用户ID，并且确认他已经成功登录校内，接下来就是处理你自己的业务逻辑。比如在你的数据库里新增加一个用户，并绑定到这个校内ID上，然后对该用户进行某些操作。最后就是返回页面内容。

这里就到了iframe和xnml模式的区别。如果是iframe模式，你返回的页面内容直接显示在iframe里，那自由度就大多了，跟普通的网页一样，想怎么做就怎么做。不过要小心iframe跨域的js问题。

如果是xnml模式，你返回的内容（还是普通的html，但是没有body标签了）是由校内的api服务器接收到的，他们对内容进行解析，然后显示在自己的层里，展现给用户。为了防止一些非法操作，xnml规定了哪些html语法是合法的，如果出现不合法的语法，会直接报错。（这里又缺少一个可用的debug方式，一旦在这个步骤出现页面错误，极难调试。）Wiki的文档里写了这里是不允许出现自己的css语法的，但是实际上现在又是可以用css的，至少style和class两个关键字都是允许的。除了普通的html语法，xnml还定义了一些他自己的语法，通过这些语法，你可以在页面上直接显示出用户的姓名头像链接好友等等信息，而无需在你的程序里通过API调用去获取。

如果你要使用form来post数据，把form的action定义成相对路径，相对于你的这个应用的实际路径，比如，如果你的原始action应该是www.aaa.com/xxxxx/save.jsp，那么只要写action=’save.jsp’就可以了，在显示出来的时候，校内会将它替换成他们自己的相对路径，然后转发到正确的地址。

最后说说最有技术味道的东西，对校内API的调用。

现在校内一共只公开了为数不多的几个API，可以获取用户信息，好友信息，给用户发通知，现在还可以增加用户的新鲜事。对这些API的用户方式都是通过Post来实现的，Post的地址是固定的，就是这个地址：http://api.xiaonei.com/restserver.do，你需要对这个地址进行Post，发送几个参数过去，包括api_key，session_key，也就是校内传过来的那两个值，还有method，就是你要调用的方法名，然后不同的方法需要使用不同的参数，这些就可以去看校内的API文档了。这些参数Post过去以后，校内会返回一个xml，（虽然所有的调用都有个response格式的参数，可以选择xml还是json，但是，即使你选了json，它还是返回xml。）xml里要么包含错误码，要么，包含了你需要得到的信息，自己解析一下就行了。

所有的调用过程，包括你返回的参数和传递的参数，还有校内给你的参数，全部是utf8格式的，包括你生成的html。

这里只是一个开发过程的简单描述，不涉及代码，有兴趣的可以去看看校内自己的示例代码，是java的。有必要的话我也可以用代码的方式来写个demo，看大家的需要了。（论坛上面的hello world的demo对于实际开发的帮助几乎为0）。