API设计参考(附Python SDK例子) – Perchouli 的技术文章和其他文章Blog

在Web应用中，API（Application Programming Interface 应用程序接口）的使用频率非常高，Google、推特、脸书，每天都会处理几十亿次的API调用请求。API接口一旦公布很难修改，所以设计要慎之又慎。本文主要归纳几种流行的Web应用API接口，总结它们的特点，供需要设计API的开发者作为参考。如果只需要RESTful的API模版建议参考Swagger。顺带介绍编写Python SDK调用API的技巧，最后是用作为例子的多说Python SDK。

几个常见的API对比

右图是ProgrammableWeb中最流行的几种API的整理：

支持协议：REST实质上是一种架构，ProgrammableWeb标注为协议(Protocols)，专指利用URI直接访问资源的方式，所以协议上标明是REST并不代表它的URI形式也符合REST。如图所示，除了Youtube，其他几种API都采用了REST架构，甚至只提供Gdata的Youtube，都有开发者用Ruby给它加了一个REST的外壳。所以如果是一个新项目，API从一开始就采用REST架构比较好。

数据格式：所有API都支持XML。FB标注的是只支持XML，但根据之前开发的经验，请求FB的Graph数据返回的也是JSON，只有Twillo是只提供XML格式。JSON格式更简单，缺点是失去了命名空间等高级特征，而且不像XML有很多现成的开发工具。但“开发人员友好性”是API首要考虑的问题，能两种格式都能支持当然会更好，如果开发时间有限，综合来看可以选择先支持JSON。

接口请求地址：大部分API的请求URI都是全小写，下划线分割。Flickr，Google search，Twilio带有版本号（其中Twilio比较奇怪的是用日期作为版本号）。REST只强调URI对资源的指向，没有规定说地址一定要采用哪种形式。例如资源提供端是用Python写的，那API的URI一般是下划线分割；之前参与过一个Java网站的项目，API就是驼峰命名。

国内的API没有列出来，因为它们文档中并没有明确说明是否采用了REST或是其他架构。数据格式上，新浪API是只提供JSON格式，Dnspod的API支持XML/JSON，多说支持JSON/JSONP。接口请求地址，开心网是下划线分割，多说是首字母小写驼峰命名，DnsPod以.分割例如User.Under。

用Python写SDK

SDK要符合开发者的习惯，Python变量和函数都是用下划线分割，所以SDK最好避免使用其他方式命名的函数；引用模块/方法是用句号(.)，实际使用时，用users.details(user_id=1)最符合Python的思维模式。实现这种调用方式当然不可能是去写一个user函数，API的接口很多。

在调用Python类中不存在的属性时，会抛出AttributeError的错误。调用类成员方法__call__和__getattr__对它进行处理，将属性/方法作为实际需要调用函数的参数即可，以下是简单的例子：


import urllib

class DuoshuoAPI():
    def __init__(self, attr=None):
        self.attr = attr

    def __getattr__(self, attr):
        #应该先判断传入的attr是否已经存在，参考完整例子
        return DuoshuoAPI(attr)

    def __call__(self, **kwargs):
        return self._request(**kwargs)

    def _request(self, **kwargs):
        param = ''
        for k, v in kwargs.iteritems():
            param = '%s=%s' % (k, v)

        url = 'http://dmyz.org/%s?%s' % ( self.attr, param) 
        return  url

if __name__ == '__main__':
    api = DuoshuoAPI()
    print api.user(user_id=123)

运行这个例子会打印出 http://dmyz.org/user?user_id=123 。

多说的Python SDK

多说是我现在参与的项目，产品见本站的评论框。界面和功能上，我认为多说比其他同类产品都要好，要做深度整合，多说最合适。国内其他社会化评论框大多都是用iframe来实现的，对没有网站开发经验的人来说没什么区别，也少了很多兼容性的问题，但操作iframe中的元素有诸多限制。所以如果一开始就打算自己动手修改，建议选择多说。

这个SDK参考了Disqus，增加了两个处理，一是用interface.json定义所有的接口，包括接口路径，请求的数据格式，请求的协议(目前只有POST/GET)；二是用Resource这个类来处理request，DuoshuoAPI继承Resource。

插件目前在Django中使用最多，所以SDK中提供把Django comment中的评论导入到多说的功能，需要使用SDK可以在Github下载或直接点下面的按钮Fork。

多说的通用代码已经在Django，TurboGears，Web2Py的生产环境上测试通过了，当然通用代码和底层框架无关，就是一段Javascript代码用来加载评论框，只是说在这三个框架上做的整合比较深，有更多可以参考的代码，想试用这个产品请戳这里：http://duoshuo.com/create-site 。任何关于评论框和/或SDK使用上的问题都可以评论或是邮件联系我。