app和后端的交互,一般都是通过后端提供的api实现。api的设计,估计很多刚进入app后端的小伙伴会一无头绪,不知道怎么入门。下面根据自己3年的app后端经验,总结出下几个api设计原则,给小伙伴参考。

1. 什么是api?

  这个问题在以前发表的文章“7.app和app后端的通讯”中其实已经回答了,这里再重复一次。





  相信大家都用过银行的柜员机(ATM)的查询余额,转帐,取款等操作。





  当在柜员机取款的时候,我们输入要取款的金额,隔一会钱就出来了,如果因为有什么问题不能取款(例如超过取款金额的限制),屏幕上也会显示出错误的信息。





  在整个过程中,我们只要输入金额,获得结果(取款成功或不成功),就行了,至于柜员机内部是怎么处理,我们不需要理会。





  柜员机这种把内部的处理遮蔽的做法极大方便了我们的使用。





  同样的,在后端,也只提供了一系列的功能给app使用,这系列的功能以api的形式提供。





  api的定义:API(Application Programming Interface,应用程序编程接口)是一些预先定义的函数,目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力,而又无需访问源码,或理解内部工作机制的细节。





  当app调用api的时候,只需要明确下面3点:





  1.这个api是干啥的(柜员机例子中,是取款功能,还是查询余额,还是转账)





  2.知道要输入什么(柜员机例子中,取款要输入金钱)





  3.知道结果是什么(柜员机例子中,取款是成功还是失败)





  至于api内部是怎么处理的,app根本无需理会。





  从这里可看出,api能在最大程度遮蔽了app后端复杂性,极大提高了app前端的开发效率。

2. api设计的8点

  (1)Restful设计原则





  Restful风格:RESTfu设计原则,它被Roy Felding提出(在他的”基于网络的软件架构“论文中第五章)。而REST的核心原则是将你的API拆分为逻辑上的资源。这些资源通过http被操作(GET ,POST,PUT,DELETE)。





  在实际的开发过程中发现,程序员由于在web端养成的习惯,api操作中通常就只有两种方式"POST""GET"。大家可看一下微博的api例子"statuses/destroy",这个很明显是delete操作的api却是用post方式提交。不是完全遵守Restful风格的风格。





  这个设计原则最简单的应用就是根据object而不是页面来设计api。最开始的时候,app的一个页面需要什么数据,api就返回什么数据。结果随着app的UI不断改版,需要的数据不断变化,不停地修改api,最后当api的改动会影响以前的版本的时候,只能写一个新的api版本,最后弄得api中有很多V2,V3这样的标志,恶梦!





  后来在网站的重构过程中,就根据object来设计api,但根据object来设计,又有一个问题,一个大object可能包含很多小object,是一个api返回全部小object,还是分为多个api返回?根据业务和技术,带宽等仔细考虑吧。





  (2) api的命名





  一看api名字就知道这个api是干啥。在创业团队中,一般就只有一两个人负责后台,当你要负责几十甚至上百个api,你就知道不能“望名知api”是个什么样的痛苦。





  api的命名,我是挺喜欢微博的命名风格,例如删除微博的api "statuses/destroy",第一个是对象,第二个是对象的操作删除





  (3)api的安全性





  这点会在以后的“怎么保证app通讯的安全性”一文中详细论述。





  (4) api返回数据





  app客户端的语言 java 和object-c都是强类型语言,所以怎么处理空值显得特别重要,不合理的设计很容易造成app的闪退。





  从后台的角度来说,api中返回的数据中,正确值和空值的类型必须一样,举例,用户名的字段是“realname": "xxx”,如果用户名为空,则应该返回“realname": ""。如果返回值是一个array,空数据则返回一个空array,绝对禁止null值。





  对于客户端,必须用个全局的函数来处理所有api的返回数据,需要有一个机制:对于某个客户端需要数据,如果api中缺失,客户端自动补上并给予默认值。这个机制在我们的实践中大大减少了app的闪退。





  同时,在数据库设计的时候,一个合理的设计必须是所有字段都有默认值,不应该允许null值。null在大量的语言和数据库中,会带来无穷的问题。对于这个数据库设计原则,我以前不太明白,现在经历了一年的api设计后,终于懂得。





  如果客户端是php,还有一个问题,php中数组和字典都是array,但在java 和object-c中是不一样,这个问题一定要注意。





  (5)图片的处理





  在不同版本的app中,各种不同尺寸的手机中,同一张图片显示的尺寸可能是不一样,如果每次都需要用返回原图,然后在客户端处理,则极大浪费网络资源。而如果是后台处理好图片才返回,则又是一个挑战,怎么有效保存和裁剪多种图片尺寸呢





  例如,一开始头像只需要返回60*60的尺寸,后来在新的版本需要返回70*70, 又出了一个新版本,需要返回80*80, 每次增加一个新的尺寸,怎么在数据库上记录下来。这个问题在一开始做api的时候没考虑,后来不得不用了一个极端的方法,没增加新的图片尺寸,就在数据库中增加一个新的字段,保存并生成新的图片尺寸,结果最后数据库的头像字段有"avatar","avatar_60_60","avatar_70_70","avatar_80_80",这种极度恶虐的设计。





  最后,针对图片,我们才用了这样的策略:





  (1)客户端本地缓存图片,只有没有合适的图片,才去服务器取。





  (2)当客户端需要某种尺寸的图片,由客户端告诉服务端图片的尺寸,服务端动态生成并缓存起来。





  例如,客户端需要图片(http://www.baidu.com/img/bdlogo.gif)的80*80的尺寸,则在图片的路径加上宽和高的参数(类似于CDN的机制) http://www.baidu.com/img/bdlogo.gif?w=80&h=80, 则服务器就生成80*80的尺寸并返回。





  采用了这样的图片处理机制,数据库中只要有一个字段保存原图就行了,其它尺寸就由客户端告诉服务端动态生成。以后无论什么尺寸的图片,数据库中都不需要记录,数据库只有原图就行了。





  注意,现在的文件云存储服务(例如七牛,又拍云)等都提供了这个文件的缩放功能,而且能加速文件的上传下载速度,极大提升了app的用户体验,强烈推荐使用。





  (6)返回的提示信息





  最科学的情况,服务端只返回信息代码,具体的文字提示由客户端决定。





  如果文字信息是由服务端返回,则最起码要区分2种信息:提示用户的信息,提示客户端程序员的信息。这两者的区别:





  1.提示用户的信息是要在让客户知道的,提示客户端程序员的信息不需要让客户知道的。





  2. 提示用户的信息文字很友好,客户不需要专业基础一看就知道是什么,提示客户端程序员的信息则很专业,例如告诉客户端少传了哪个参数?哪个参数有问题等等。





  (7)在线api测试文档





  我们网站的api在线测试文档,是使用既是一份在线api文档,也是一个在线测试工具,极大方便沟通和测试。每次客户端程序员觉得某个api有什么问题,我们就是这个在线工具上讨论沟通的。客户端程序员最喜欢这个玩意了^-^。





  这个api在线测试文档,是使用了Swagger-UI搭建的。Swagger-UI简单而一目了然。它能够纯碎的基于html+javascript实现,只要稍微整合一下便能成为方便的API在线测试工具。项目的设计架构中一直提倡使用TDD(测试驱动)原则来开发,swagger-ui在这方面更是能提供很大帮助。





  下面是用Swagger-UI搭建的api文档中的一个api的例子,可看到,整个api的提交方式,作用,参数都非常清晰明了。





  当按了“测试”,就以post方式调用这个api,返回的结果如下:





  所有的返回结果,一目了然,cool!!!





  api返回的数据,是以json格式返回的。用json格式,最省流量,而且几乎每种计算机语言都支持json格式。用xml的话,太耗费流量了,而且冗余数据多,不适合移动端。





  在"app后端"的qq群,有个app创始人使用了这个api在线测试文档后赞不决口,称赞虽然前期的搭建需要花一段时间,但极大提高了app前后端工作的效率。以后有小伙伴问相关的问题,他都强烈推荐这个Swagger-UI。





  (8)在app启动时,调用一个初始化api获取必要的信息





  通过这个初始化api,获取一下必要的信息,例如,最新的app版本。当发现本地app的版本已经低于最新的app版本,可提示用户更新。当然了,这个提示版本更新的功能很多第三方sdk都提供。

3.如何处理api的版本升级

  当app做了大改版后,可能会出现一个问题,发现现在的api已经不适了,就考虑到api的升级,同时为了兼容已经发布的app,原来的api必须要保留。为了避免同一个app中调用不同版本的api,一般就会全部升级api的版本,例如:原来的是“test.com/v1/statuses/destroy”,升级为“test.com/v2/statuses/destroy”。





  在api的版本升级时,需要注意以下2点:





  1. v2版本的api的controller必须要继承v1版的controller,v2版本的api只重写需要改动的api。

  2. 在线api测试文档中详细标明返回内容,已作对比,方便客户端人员的调试。

---------------------------------------------------------------------------------------------------------------------------

打开链接  app后端系列文章总目录 总目录 ,能查看本人发表过的所有原创“app后端”文章。

【作者】曾健生

【QQ】190678908

【app后端qq群】254659220 

【微信公众号】 appbackend

【新浪微博】 @newjueqi

【博客】http://blog.csdn.net/newjueqi


版权声明:本文为博主原创文章,未经博主允许不得转载。

14.app后端如何设计api的更多相关文章

  1. app后端架构设计(转)

    (1)Restful设计原则 Restful风格:RESTfu设计原则,它被Roy Felding提出(在他的”基于网络的软件架构“论文中第五章).而REST的核心原则是将你的API拆分为逻辑上的资源 ...

  2. 15.app后端怎么设计用户登录方案

    在很多app中,都需要用户的登录操作.登录,就需要用到用户名和密码.为了安全起见,暴露明文密码的次数越少越好.怎么能最大程度避免泄露用户的密码呢?在登录后,app后端怎么去验证和维持用户的登录状态呢? ...

  3. app后端设计--总目录 (转)

    特此说明,我转载的!!! app后端设计(1)--api app后端设计(2)--xmpp的使用 app后端设计(3)--短信,邮件,推送服务 app后端设计(4)-- 通讯的安全性 app后端设计( ...

  4. app后端设计--总目录

    做了3年app相关的系统架构,api设计,先后在3个创业公司中工作,经历过手机网页端,android客户端,iphone客户端,现就职于app云后端平台bmob(想了解bmob点击这里).其中的乐与苦 ...

  5. 16.app后端如何保证通讯安全--url签名

    app和后端的通讯过程中,api请求有可能被别人截取或不小心泄露.那么,怎么保证api请求的安全呢?在这篇文章中,介绍一种常见的保证api请求安全的做法--url签名. 1. url签名详解 在前一篇 ...

  6. ****RESTful API 设计最佳实践(APP后端API设计参考典范)

    http://blog.jobbole.com/41233/ 背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中“RESTful API ”简写为“API”)如何设计的文章,然而 ...

  7. app后端设计(2)--xmpp的使用(2014.01.14更新)

    在app中有时候是需要添加聊天服务,在这里谈谈曾经开发聊天服务的经验: (1)聊天服务端选的openfire,这是一个基于xmpp协议的聊天服务器(XMPP是一种基于XML的协议,它继承了在XML环境 ...

  8. app后端设计(14)--LBS的偏移问题

    刚开始做LBS的时候,有一个问题,通过手机获取的坐标,放到百度地图或高德地图上,总是会出现偏移,例如,当时是在微信的前总部"南方通讯大厦"附近获取的坐标,那是把坐标放到百度地图上却 ...

  9. app后端设计(12)--图片的处理

    app上线后,不断接受用户的反馈,于是,反馈非常差的情况下,都会有app的改版. 一旦app的改版,都会有比较大的UI改动,一改动UI,那么图片的尺寸也就必须要改变. 在app后端设计(1)—api( ...

随机推荐

  1. linux 查找文件或者内容常用命令

    whereis <程序名称> find [路径] <表达式> locate <文件名称> 从文件内容查找匹配指定字符串的行: $ grep "被查找的字符 ...

  2. 仿网易新闻 ViewPager 实现图片自动轮播

    新闻 App 首页最上方一般会循环播放热点图片,如下图所示. 本文主要介绍了利用 ViewPager 实现轮播图片,图片下方加上小圆点指示器标记当前位置,并利用 Timer+Handler 实现了自动 ...

  3. 如何分析解读systemstat dump产生的trc文件

    ORACLE数据库的systemstat dump生成trace文件虽然比较简单,但是怎么从trace文件中浩如烟海的信息中提炼有用信息,并作出分析诊断是一件技术活,下面收集.整理如何分析解读syst ...

  4. 【转】Android布局优化之ViewStub

    ViewStub是Android布局优化中一个很不错的标签/控件,直接继承自View.虽然Android开发人员基本上都听说过,但是真正用的可能不多. ViewStub可以理解成一个非常轻量级的Vie ...

  5. linux下创建的符号链接的权限

    今天为shell脚本创建符号链接的时候突然发现的, 创建的符号链接文件的默认权限是 777, 而想要这个脚本可执行, 必须为真正的文件加上 x 权限才可以.

  6. oracle中的exists 和not exists 用法 in与exists语句的效率问题

    博文来源(oracle中的exists 和not exists 用法):http://chenshuai365-163-com.iteye.com/blog/1003247 博文来源(  in与exi ...

  7. MySQLdb安装和使用2

    http://blog.chinaunix.net/uid-8487640-id-3183185.html MySQLdb是Python连接MySQL的模块,下面介绍一下源码方式安装MySQLdb: ...

  8. 怎样检查手机是否root成功

    怎样检查手机是否root成功 浏览:154361 | 更新:2011-01-20 13:10 | 标签:root 总有人以为,root后就可以删除自带程序了,这个想法也对也不对,想删除自带的软件,确实 ...

  9. bzoj1751 [Usaco2005 qua]Lake Counting

    1751: [Usaco2005 qua]Lake Counting Time Limit: 5 Sec  Memory Limit: 64 MB Submit: 168  Solved: 130 [ ...

  10. Allegro的优点与缺点

    记得刚毕业出来时就在某台商工作,用的就是allegro,从此上了贼船就下不来了--.其实还用过pcad,protel,powerpcb(以下简称3p,加上pads就4p了,呵呵--).至于mentor ...