RESTful API调用初体验

公司的人事管理信息系统采用的是美国一家大型应用服务提供商---ADP提供的服务( http://www.adp.com/ , http://www.adpchina.com/html/about/) 。今年6月份，HR系统从原来的ADP HRB V2 一下子升级到了现在的ADP WFN V11 。

HR系统升级后，各方面都增强了，但也有一点不好，就是新系统不再支持自动导出员工有关数据并上传到SFTP服务器。公司AD数据需要根据HR系统导出的数据每天同步更新。为了保持HR与AD之间的同步，我临时开发了一个Windows桌面程序，以便美国HR系统管理员将他手工导出的数据上传到SFTP服务器。但手工导出上传只是权宜之计。不久公司就订购了ADP的WFN API服务。公司最终目标是通过API调用实现HR与AD之间的近实时同步, 而近期目标是自动生成员工数据报表并自动上传到SFTP服务器, 完全代替系统管理员的部分手工工作。

ADP提供了一份长达56页的有关如何调用WFN API的数据字典。我快速浏览了数据字典，文档里多次出现OAuth2, RESTful, JSON等字眼。这些对我来说是新东西，有些概念有听说过, 但还没实际接触过。百度了一下有关词条，感觉有信心学习掌握这些新知识。当美国那边问我能不能开发这个API调用程序时，我毫不迟疑地回答说没问题。

接下来准备开发这个API tool。目前正在运行的 AD sync tool 我是用VB.NET开发的，为了有利于今后的系统集成，API tool 我也决定用VB.NET来做。申请安装Open SSL, 生成CSR发给ADP, ADP返回包含有PFX证书的PEM文件，拿到PEM文件后自己生成本机的PFX证书,然后 通过mmc来安装证书。除了安装好证书外，想通过Google Postman来调试WFN API, 每次都需要向ADP请求一个不记名令牌Bearer Token. 而要获得Bearer Token,需要将ADP提供的OAuth2用户名和密码进行64位加密,用加密后的凭据构成身份验证头,再通过https发送到ADP的账户验证服务器进行验证。如果验证成功，验证服务器会返回一个在一小时内有效的令牌。

几经偿试，在PostMan中可以成功返回所需的员工数据了。到这一步只是确认了OAuth2验证机制在本机可以正确工作而已，而要在自己程序中实现这些功能还需要费一番功夫。首先是要让程序自动获取已安装的证书。网上现成的例子找不到。搜索了很多资料才找到可行的DOT NET方法。构建验证头时，也遇到一些麻烦。解析服务器返回的令牌倒很顺利，因为那几行的JSON数据结构非常简单。可是在解析大批量返回的员工数据时，还是碰到不少问题。员工数据属性多，层次多; 美国员工具有的某些属性而中国员工却没有; 早期录入的已离职的员工可能有特别的数据格式等等。解析时需要有足够多的不同员工样本才能覆盖所有情况。读取不存在的外层对象和内层属性时会出异常，需要进行多层次的异常处理。另一个麻烦的地方是，目前WFN导出用于AD sync的数据有两千两百多条(数量还会不断增长), 而WFN API不允许一次性获取全部两千多条数据, 默认一次只能读取50条数据。因此，程序中必须循环动态生成带参数的URI进行调用, 每次读取50条直至两千多条全部顺利读完。如遇到网速慢或服务器忙，每次调用URI都有可能超时或服务器返回内部错误，此时程序应该设置间隔一定时间后多次重试，待读取成功再进行下一URI调用。每一次读取并解析成功的数据都及时写入CSV格式的报表文件中。全部读取完成后，API tool 将报表做适当处理，然后直接上传到SFTP服务器指定目录中，供AD sync tool使用。网络和服务器正常时，全部读取两千多条数据需要用时约25分钟。

这个API tool从开始开发到完成将近一个月时间(期间我还花一些时间用于开发IT资产管理信息系统网站)，项目总体进度还是比较快的。经过一段时间连续测试，确认运行稳定，数据准确。现在已经通过美国方面批准，准备于元旦后将API tool部署到生产环境中。

RESTful Web API 风格目前比较流行，对大多数应用场景来说也是有优势的。目前我只是成功学习使用了如何调用API，今后有机会在合适的场景要多学习设计符合规范的RESTful API服务供别人调用。

12/27/2016写于厦门