好的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. 游戏行业 ...
随机推荐
- npm 国内淘宝镜像cnpm、设置淘宝源
1.下载和使用cnpm 某些插件很奇怪,需要用国内的镜像下载才可以 #安装淘宝镜像npm install cnpm -g --registry=https://registry.npm.taobao. ...
- SpringBoot进阶
一.表单验证 二.AOP处理请求 AOP是一种编程范式.与语言无关,是一种程序设计思想. 面向过程到面向对象.换个角度看世界,换个姿势处理问题. 2.1AOP实例-http请求 MAVEN添加依赖:o ...
- 如何设置Docker容器中Java应用的内存限制
如果使用官方的Java镜像,或者基于Java镜像构建的Docker镜像,都可以通过传递 JAVA_OPTS 环境变量来轻松地设置JVM的内存参数.比如,对于官方Tomcat 镜像,我们可以执行下面命令 ...
- 国际化模块 angular-translate 简单方便快捷翻译中英文等多语言环境
很多web服务面对的不仅仅是当地用户,多语言环境不仅能提升逼格,更重要是一种用户体验. angular.js 作为前后端拆分的解决方案之一,当然离不开前端框架处理国际化的问题,angular.js 官 ...
- vue自动化单元测试
// 引用vue和需要测试的组件 import Vue from 'vue' import HelloWorld from '@/components/HelloWorld' // 创建测试套件,一个 ...
- Python中的相对文件路径的调用
先让我们来看看一个用到相对文件路径的函数调用的问题.假设现在有两个脚本文件main.py和func.py,他们的路径关系是: . |--dir1 |--main.py |--dir2 |--func. ...
- tomcat事件处理机制
最近在阅读“how tomcat works”这本书,结合tomcat7的源码进行学习.对于学习的收获,将通过“tomcat学习系列”记录下来,和大家一起分享和交流,也算对自己学习的一种促进.闲话不多 ...
- 利用BioPerl将DNA序列翻译成蛋白序列
转自 https://www.plob.org/article/4603.html 具体请去上面的网页查看. my $DNA="ATGCCCGGT";my $pep=&Tr ...
- 纯css3实现的幽灵按钮导航
之前为大家介绍了好几款导航菜单,今天再给大家带来一款css3实现的幽灵按钮式的导航菜单.导航界面非常好看.右侧是一个css3实现的动画消息图标.效果图如下: 在线预览 源码下载 实现代码: htm ...
- javascript-删除节点
任务目的: 每点击一下按钮删除一个标签. 掌握到了: 这里是主要学习到了parentNote以及removeChild两个DOM属性. parentNote:parent英译为父亲,Note英译为节点 ...