Python Tech

API设计参考(附Python SDK例子)

在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使用上的问题都可以评论或是邮件联系我。

avatar

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据

  Subscribe  
最新 最旧 得票最多
提醒
muxueqz即明源是也
游客

原来兄弟现在在duoshuo.com , 之前考虑用来作评论,不过没导入进去,反而友言试着可以导入

Perchouli
游客

是呀,我Linkedin更新了嘛。之前没有导入,以JSON格式导入评论数据到多说是最近才做好的, 今早还在修改文档… 现在用typecho呢?blog是自己用,没啥复杂需求,友言也挺好。如果是自己开发的站点,多说能减少很多代码量~