如何开发设计更加符合规范的API

原创 2018年02月03日 15:05:06

一、开发API需要考虑的几个问题


1、跨平台性


        所谓跨平台是指我们的接口要能够支持不同的终端,比如android、ios、windowsphone以及桌面软件、网站等,一套接口,支持多端,“Write Once,Run Anywhere”。当然从本质上讲,服务器端的接口跟终端是没有太大关系的,但接口应该考虑到不同端的接入成本,应根据项目或公司自身情况应该做相应的版本处理。采用通用的解决方案,比如通信协议就采用最常用的HTTP协议,如果是即时通信,可以采用开放的XMPP协议,做游戏的可以采用可靠的TCP协议,除非TCP不够用了,再采用定制的UDP协议。数据交换采用xml或者json格式等等,因自己所处环境具体情况而定。总之,要达到的目标就是让不同的端能够很方便的使用你的接口。已知现实情况:
  • 正规的API设计接口规范文档,已App界面为功能导向是设计移动端接口。意义:后端开发成本高,接口页面规范可查,App接入成本低,App维护性高。沟通成本低,对业务理解能力门槛低!
  • 另类的设计,已后端业务为导向,提供大而全的API设计接口,以满足所有端的所有需求,接口传入各种各样的配置和参数,。意义: 后端开发成本低,App接入成本很高,App后期的维护性低,维护成本高,沟通成本高,对业务的理解能力门槛高!

2、客户端与服务端的肥瘦平衡


        在以前C/S、B/S架构时,就已多次讨论过这个问题,客户端是瘦点好还是肥点好,当然也没有固定答案,需要自己根据实际情况去做权衡。客观原因,在移动APP开发中,由于客户端的修改会很费时费力,一是App应用需要经过各种渠道审核,耗费时间。更新修复问题的时间成本过高。另外,当前IOS开发人员、Android开发人员的人工成本普遍较高,人才紧缺,基于这两点,能在服务器端实现的功能就不要放在客户端,毕竟服务器端程序的修改要比客户端方便、灵活、快捷的多。作为项目负责人或技术负责人该站在什么角度去看这个问题?肥瘦平衡最终追求的是什么?。


3、考虑移动端的网络情况和耗电量


        对于移动APP开发者来说, 网络流量和电池电量是不得不考虑的问题。不过,您也许会说,这些跟接口没啥关系吧,服务器端的接口还能管得了客户端的网络流量和电量?
  • 对于网络情况,接口应该具备为不同的网络提供不同的内容的能力,通常,移动端的上网方式无非是2G(GSM、GPRS、EDGE)、3G(CDMA、TDSCDMA、WCDMA)、4G/5G、WIFI。设想一下,如果用户在流量需要花钱的情况下,你的app给用户展示了视频、音频、大量的图片和大量无用数据(接口中存在大量跟app页面无关的数据,俗称大而全的接口)。而没有通知用户的情况下用户会怎么想,毕竟国内的流量费用还是很贵的,应在不同的环境下提供不同的策略。
  • 对于电量,app的哪些方面会消耗电量?比如app有大量的计算、有很炫的视觉画面都会消耗电量, 另外,不断的移动网络链接也会消耗大量的电量,我们都知道移动网络是通过无线电波来通讯的,那么发射装置就需要消耗一定的电量来发射和接收无线信号。特别的是,频繁的链接会不断的切换网络设备与移动基站之间连接状态,这都会消耗一部分电量。所以,对于接口而言,尽量用少的链接传输多的数据,和尽量少的数据接收交互。

4、接口需不需要要为移动客户端考虑,做相应的API适配


        一种声音是不需要,后端写一套接口,不管是web端,Android,ios,wap等都调用相同的接口,后端维护简单。另一种声音是需要,要依据不同场景,开发相应的API接口(如移动端,web端等)。
        相对于我目前而言第二种较为合理。提供一下例证,欢迎探讨。接口不仅仅是提供数据和功能就完事了,更应该充分考虑移动端的特性,为移动端提供更加方便、快捷的接口。比如,在移动端里,下拉刷新和上拉加载更多是很常见的功能,如果接口仍然按照传统的web思路,只提供按页读取的话,就会造成移动端的额外的数据请求和计算。这时,接口就应该针对这两种类型的操作提供额外的支持。再比如,对于一个新闻阅读类的app来说,最新的新闻列表里的文章,特别是前几条,用户很容易点击进去看,而后面的老的文章列表,一来用户下滑加载好几页的情况较少,二来过时的新闻用户也很少点。如果,接口在返回新闻列表时,对于最新的列表,可以直接把文章的正文(或者部分正文,比如一屏的内容)信息一起传给客户端,这样,用户在打开新闻详情页的时候,就不用再从服务器端获取了,自然可以做到秒开。当然,客户端要跟接口做好配合,搭配好,才能最大化的提高性能。比如,移动端都有左右滑动来看上一篇、下一篇文章或者图片的功能,如果,当用户请求某篇文章的时候,服务器端顺便也把下一篇文章的内容返回回来了,那么当用户看下一篇的时候,是不是就很快了呢。当然这种preload的方案也不能滥用,如果预加载数据的命中率较低的话,也不行,白白浪费了很多的流量。


二、API接口设计构思应该思考的问题


1、实用性


        编写接口API应遵循实用性原则。
  • 数据格式:推荐使用JSON格式数据,因为JSON有较好的跨平台性,以及数据格式占用字节数较少,当然也可采用XML、TEXT作为程序开发辅助。
    1. 如:服务器返回json数据结构一般为:
    2. {
      	code:200
      	message: “success”
      	data: {
      		key1: value1,
      		key2: value2,
      		… 
      	}
      }
      code: 状态码,200表示成功,非200表示各种不同的错误
      message: 描述信息,成功时为”success”,错误时则是错误信息
      data: 成功时返回的数据,类型为对象、或数组... , 因此,data必须返回相应经过初始化的格式,数组如:[],对象:{}的格式,如果传入一个null,如果对象类型变成了String类型,那么肯定是报错的。
  • 接口执行效率(接口访问速度):APP有别于WEB服务,对服务器端要求是比较严格的,在移动端有限的带宽条件下,要求接口响应速度要快,对数据要求也比较严格,app需要什么数据就传什么数据,不可多传,过多的数据量影响处理速度,最重要的是影响传输效率和浪费用户流量。接口要规范,以面向对象的思想设计接口。
  • API缓存:对APP运行的体验和流畅性来说,适当的缓存比较重要,不管是文件缓存还是memcache缓存,能让用户感知不知不觉中对App产生好的体验。

2、易用性


1)、接口、参数命名准确:无论是接口还是参数,命名都应该有意义,让人一目了然。(接口推荐根据APP效果图栏目进行命名)
2)、一个页面尽可能就用一个接口: 现在很多的APP页面都有广告、焦点图、文章列表等,对于这些不同格式的数据,不可能都分配一个接口,这样加大了APP请求接口数,影响响应速度。建议服务器端尽可能处理好数据后通过一个接口返回给APP客户端,或把相似的部分功能合并已达到想要的效果,尽量不要出现一个页面七八上十个接口的情况。
3)、接口数据、状态:接口必须提供明确的数据状态信息,不管是成功的,还是失败的,都必须返回给APP客户端,系统级异常,业务级异常,参数及异常都应有所体现。否则,接口的协议失去了所有的意义
4)、接口要有可扩展性:方便后期功能性调整,接口应具备可扩展性,但扩展性也不能盲目不切实际的幻想可能会出现不同的数据逻辑。

3、安全性


1)、接口安全:目前一般都是在APP客户端和服务器通过约定的算法,对传递的参数值进行验证匹配。但是如果APP程序被反编译,这些约定的算法就会暴露,特别是在安卓APP中,有了算法,完全就可以通过验证模拟接口请求。或者引入jwt令牌(token)等解决方案。
2)、加密规范:在传递用户名密码时,应采用规范的加密算法如MD5、RSA、DES,进行数据通信请求。
3)、https协议 :对于敏感的api接口,使用https协议 ,也是一种不错的选择,这也是一个趋势。https是在http超文本传输协议加入SSL层,它在网络间通信是加密的,所以需要加密证书。https协议需要ca证书,一般需要相应的费用成本。


4、版本兼容性


        接口不可能永远不变,它会随着需求的变化而做出相应的变动。接口的变化一般会有几种:
1)、数据的变化,比如增加了旧版本不支持的数据类型
2)、参数的变化,比如新增了参数
3)、接口的废弃,不再使用该接口了
        为了适应这些变化,必须得做接口版本的设计。实现上,一般有两种做法:1、每个接口有各自的版本,一般为接口添加个version的参数。2、整个接口系统有统一的版本,一般在URL中添加版本号,比如http://api.demo.com/v2。
        大部分情况下会采用第一种方式,当某一个接口有变动时,在这个接口上叠加版本号,并兼容旧版本。App的新版本开发传参时则将传入新版本的version。如果整个接口系统的根基都发生变动的话,比如微博API,从OAuth1.0升级到OAuth2.0,整个API都进行了升级,那同样API必须做相应变化。有时候,一个接口的变动还会影响到其他接口,变动时需先想梳理清楚可能会涉及的接口。在做相应的变更处理。


        总之根据自身业务需求针对性的开发与用户习惯相应的页面设计和App接口方案才是最理想的考虑方式方法。

版权声明:转载时请标注http://blog.csdn.net/zhihua_w

开发PHP软件配置和介绍

开发PHP软件配置和介绍 编辑软件 推荐 JetBrains PhpStorm 10.0.1数据库管理软件 推荐 navicat服务器ssh管理软件 推荐 PortableGit 开发...
  • lifei191042
  • lifei191042
  • 2017年06月13日 15:55
  • 380

REST服务的URI设计

REST服务的URI设计 第一前言 第二什么是资源怎么抽离 第三URI命名规范 第四重点 第一:前言 我们一般写API常用的逻辑思维是以“动作”为中心,比如购买商品,要查询商品列表...
  • achenyuan
  • achenyuan
  • 2018年01月16日 20:25
  • 29

C++ API设计—— API简介

APT:提供了对某个问题的抽象,以及客户与解决该问题的软件组件之间进行交互的方式。 API设计上的不同:1)要保证有良好的设计2)精心编写、术语一致且内容全面的文档3)有一套完整的回归测试验证并未...
  • lxy_2011
  • lxy_2011
  • 2017年06月29日 11:42
  • 438

ECharts动态加载数据(简单)

Echarts动态加载数据
  • im_zhq
  • im_zhq
  • 2016年12月15日 22:36
  • 228

排序1——冒泡排序及优化

冒泡排序及其优化
  • m0_37105443
  • m0_37105443
  • 2017年06月24日 17:03
  • 139

判断IP、MAC地址是否符合规范

#include #include #include #include #include int is_valid_ip(const char *ip) {     if (ip == N...
  • u013022032
  • u013022032
  • 2016年01月14日 08:57
  • 239

排序算法入门之冒泡排序优化

这篇文章是对上一篇文章中的冒泡排序进行优化 先来说说,冒泡排序哪些地方需要优化: 根据上一篇文章的内容,可以知道冒泡排序的核心是两两对比进行交换。如果有一个无序数列(2,1,3,4,5,6,7,8...
  • qq_35114086
  • qq_35114086
  • 2016年09月12日 18:05
  • 219

程序开发设计API大全 下载

注:更多资料,尽在本人网盘 http://page1.yunfile.com/ls/baoquan1412/  http://filemarkets.com/file/baoquan1412/5a...
  • u010820783
  • u010820783
  • 2013年05月28日 20:37
  • 534

如何深入和高效的学习编程语言

如何深入和高效的学习编程语言
  • wusimin432503
  • wusimin432503
  • 2017年09月22日 00:28
  • 1033

对符合规范

希尔也同意恢复高消费兔兔房交会系统
  • dfhdfghsfg
  • dfhdfghsfg
  • 2010年02月09日 12:25
  • 105
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:如何开发设计更加符合规范的API
举报原因:
原因补充:

(最多只允许输入30个字)