好的API设计
[非原创,原文链接]
API设计书籍下载:
最近在重构公司的一个交互中间件,在重新设计API及总体架构的时候思考了许多, 不禁萌发了一个疑问,什么样的API才算是一个设计良好的API呢?
参考了许多的资料,做一下总结。主要来自这个keynote
什么是API
我们只要是在进行编程我们就需要不停的设计API,
API简单来讲可以是一个调用的函数,一个接口。抽象来说:接口是一个内聚系统暴漏给外部的一切信息。 包含但不限于:
- 调用方式:比如通过lib库或者http接口等
- 调用约定:比如lib的函数签名或者HTTP的参数,http method或者头信息,长短链接等等。
- 依赖关系:比如接口的调用需要涉及到第三方或者其他的准备工作等等。
设计良好API的特点
这里探讨的API均为系统边界的API设计,而对于内部API来说不在探讨范围之内。
变动困难
API就像一个人一样,我们和一个API打交道的时候需要了解这个人的特性偏好等, 有的人很好相处,而有的人让人很头疼,尤其是你不得不和他打交道的时候。
和人一样,如果你不得不和他打交道,要改变他的秉性是很痛苦的,人的“本性难移”, API也一样,一旦发布了,要改变的成本就很大很大。
好的API应该具有:
- 易于学习
- 即使没有文档也易于使用
- 不易误用:这一点很重要,要减少使用者的心智负担
- 使用API的代码易于维护。这个有点不一样,不是API本身易于维护,而是API的友好度。 比如接口功能单一,使用简单,使用者的代码也会相应的更易于维护
- 易于满足需求:API的完备性和正交性。能够容易的满足需求,完备性保证功能完整, 正交性保证接口的简洁性,不需要为所有的需求提供接口,而是由用户去组合。
- 易于扩展
怎么样设计良好的API
基本原则:
- 专一:一个API的功能应该是单一的,需要能够很容易的解释和理解,也就会更好用。
- 尽可能的小:小有很多的优势,易于理解和维护。
- 尽量少的外部依赖:减少使用者的成本
- 设计不被实现影响:不要暴漏实现细节给用户
- 竟可能少的暴露,不止是内部细节,对于不必要的接口尽量不要发布,比如使用不多的功能, 可以暂时不暴露接口。
- 良好的命名:尽量做到自描述。
- 完善的文档
- 考虑性能
其他具体的方法还是参考后面参考资料的内容吧。
参考资料
- http://mattgemmell.com/api-design/
- http://lcsd05.cs.tamu.edu/slides/keynote.pdf
- http://ishare.iask.sina.com.cn/f/61717785.html
- http://qt-project.org/wiki/API-Design-Principles
- http://www4.in.tum.de/~blanchet/api-design.pdf
好的API设计的更多相关文章
- javascript的api设计原则
前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块.系卤煮自己总结的一些经验和教训.本篇博文同时也参考了其他一些文章,相关地址会在后面贴出来.很难做到 ...
- (转载) RESTful API 设计指南
作者: 阮一峰 日期: 2014年5月22日 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制 ...
- RESTful API 设计指南
转自:http://www.ruanyifeng.com/blog/2014/05/restful_api.html 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机. ...
- GOTO Berlin: Web API设计原则
在邮件列表和讨论区中有很多与REST和Web API相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ的首席顾问Oliver Wolf在GOTO Berlin大会上开始自己的 ...
- RESTful API 设计最佳实践
背景 目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个"万能"的设计标准:如何鉴权?API ...
- 我所理解的RESTful Web API [设计篇]
<我所理解的RESTful Web API [Web标准篇]>Web服务已经成为了异质系统之间的互联与集成的主要手段,在过去一段不短的时间里,Web服务几乎清一水地采用SOAP来构建.构建 ...
- 从英文变形规则计算到Restful Api设计
➠更多技术干货请戳:听云博客 一天在研究Restful API设计,命名的时候我总是很纠结,我相信大多数人也有这种感觉,不是说想不出来某个单词怎么写的问题,像我这种没事背单词背到13000词量的人也要 ...
- RESTful API 设计指南 (转)
RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...
- 基于资源的权限系统-API设计
概述 权限系统需要和别的系统集成,因此,良好的API是易用性的保证. 这里只设计一些权限相关的核心 API,关于用户,组织,导入导出之类的后续再逐步补充 API 设计 围绕权限有以下 4 类 API: ...
- Atitit. Api 设计 原则 ---归一化
Atitit. Api 设计 原则 ---归一化 1.1. 叫做归一化1 1.2. 归一化的实例:一切对象都可以序列化/toString 通过接口实现1 1.3. 泛文件概念.2 1.4. 游戏行业 ...
随机推荐
- java日志 -logback的使用和logback.xml详解(转)
一.logback的介绍 Logback是由log4j创始人设计的另一个开源日志组件,官方网站: http://logback.qos.ch.它当前分为下面下个模块: logback-core:其它两 ...
- html5中script的async属性
html5中script的async属性 我兴奋于html5的原因之一是一些久久未能实现的特性现在可以真正运用于实际项目中了. 如我们使用placeholder效果蛮久了但是那需要javascript ...
- Vuejs2.0 + bootstrap demo
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8&quo ...
- POI导出
public void export(){try {String columns = getPara("nameArray");List<Record> list = ...
- 判断js对象是否拥有某一个属性的js代码
js对象是否拥有某一个属性的判断方法有很多. 本文分享一个简单的方法,如下: <script> /** * 判断js对象是否具有某属性 * by www.jbxue.com */ var ...
- Android笔记一.深入理解Intent和IntentFilters(一)
深入理解Intent和IntentFiler(一) 转载请表明出处:http://blog.csdn.net/u012637501(嵌入式_小J的天空) 为了比較深刻的理解并灵活使用Inten ...
- C# 使用Nlog记录日志到数据库
[摘要]Nlog是一个很不错的.NET日志记录组件,它可以将日志输出到控件台,保存到文本,也可以很方便的记录到数据库中.本文为你介绍C# 使用Nlog记录日志到数据库. Nlog是一个很不错的.NET ...
- Python框架级编程的能力要求
说在前面:比较基础的就不说 1.装饰器熟练掌握 2.内建函数,内建变量.下划线函数之类的东西要搞明白 3.一定Python数据接口和算法实现能力 4.内省 5.元编程
- 李洪强iOS开发之极光推送JPush
李洪强iOS开发之极光推送JPush
- 经典 makefile 教程
makefile很重要 什么是makefile?或许很多Winodws的程序员都不知道这个东西,因为那些Windows的IDE都为你做了这个工作,但我觉得要作一个好的和professional的程序 ...