Effective API Design

*/-->

div.org-src-container {
font-size: 85%;
font-family: monospace;
}

A well-written API can be a great asset to the organization that wrote it and to all that
use it. Given the importance of good API design, surprisingly little has been written on the
subject. In this talk (recorded at Javapolis), Java library designer Joshua Bloch teaches
how to design good APIs, with many examples of what good and bad APIs look like.

From: Infoq.com

1 Foreword

  • Why is API Design Important?
  • APIs can be among a company's greates assets.
    • Customers invest heavily: buying, writing, learning.
    • Cost to stop using an API can be prohibitive
    • Successful public APIs capture customers.
  • Can also be among company's greatest liabilities
    • bad APIs result in unending stream of support calls.
  • Public APIs are forever
    • One chance to get it right.
    • Why is API Design Important to You?
  • If you program, you are an API Designer
    • Good code is modular - each module has an API
  • Usefull modules tend to get reused
    • Once module has users, can't change API at will

      • You can add new ones,
      • But you should not delete or modify existing ones at will.
  • Thinking in tersm of API improves code quality.
  • Characteristics of a Good API
  • Easy to learn.
  • Easy to use, Hard to misuse
  • Easy to read and maintian code that uses it
  • Sufficiently powerful to satisfy requirements.
  • Easy to extend
  • Appropriate to audience.

2 Process of API Design

  • Gather requirements - with a Healthy Degree of Skepticism
    Often you'll get proposed solutions instead, but better solutions may existing, and your job
    is to extract true requirements from the use-cases.

    And, keep in mind that it can be easier and more rewarding to build somthing more general.

  • Make spec short: single page is okey
  • Write to Your API Early and Often
  • Writing to SPI is Even More Important
    • Service Provider Interface (SPI)
    • Plugin-in interface enabling multiple implementations
    • Example: Java Cryptography Extension (JCE).
    • Write multiple plugins before release
    • The Rule of threes.
  • Maintain Realistic Expectations

3 General Principles

  • API should do one thing and do it well
  • Functionality should be easy to explain:
    • If it's hard to name, that generaty a bad sign.
    • Good names drive development.
    • Be amenable to spliting and merging modules.
  • API should be as mall as possible, but no smaller
    • API should satisfy its requirements
    • When in doubt, leave it out!
      • You can always add, but you can never remove!
    • Conceptual weight more important than bulk.
    • Look for a good power-to-weight ratio
  • Implementation should not impact API
  • Minimize Accessibility of Everything
    • Make classes and members as private as possible.
    • Public classes should have no public fields.
    • Maximizes information hiding
    • Allow modules to be used, understood, built, tested, and debugged independently.
  • Names Matter – API is a Little Language
    • Names shoudl be Largely Self-Explanatory
    • Be consistent – same word meas same thing
    • Be regular – strive for symmetry
    • Code should read like prose
  • Documentation Matters
  • Document Religiosly:
    All public APIs should have Documentation:

    • Classes: what an instance represents
    • Method: contract between method and its client
      • Preconditions, postconditions, side-effects.
    • Parameter: indicat units, form, ownership
    • Document state space very carefully
  • Consider Performace Consequences of API Design Decisions

    • bad decisions can limit performance.
  • API Must Coexist Peacefully with Platform

4 Classes Deisgn

  • Minimize Mutability
    Classes should be immutable unless there's a good reason to do otherwise. If mutable,
    keep state-space small, well-defined.
  • Subcalss only where it makes sense
    Subclassing implies subsitituability,

    • Public classses should not subclasses other public classes.
  • Design and Document for Inheritance or Else Prohibit it!

5 Method Design

  • Don't make the Client Do Anything the Module Could Do
  • Don't Violate Principle of Least Astonishment
  • Fail Fast – Report Errors as Sonn as Possible After They Occur
  • Provide Programmatic Access to All Data Available in String Form
  • Overload With Care

if you must provide ambiguous overloadings, ensure same behavior for same arguments.

  • Use Appropriate Parameter and Return Types

    • Favor interface types over classes for input.
    • Use most specifi possible input parameter type

    Moves error from runtime to compile time.

    • Don't use string if a better type exists
    • Do't use floating point for monetary values:

    Binary floating point causes inexact result.

    • Use double (64 bits) rather than float(32 bits):

    Precision loss is real, performance loss negligible.

  • Use Consistent parameter Ordering Across Methods
#include <string.h>
char *strcpy(char *dest, char *src);
void bcopy (void* src, void* dst, int n); // XXX: Bad example!
  • Avoid Long Parameter Lists

    • Three or fewer parameters is ideal
    • Two techniques for shortening parameter lists:
      • Break up method
      • Create helper class to hold parameters
  • Avoid Return Values that Demand Exceptional Processing

6 Exceptions Design

  • Throw Exceptions to Indicate Exceptional Conditions

    • Don't force client to use exceptions for control flow.
    • Don't fail silently
  • Favor Unchecked Exceptions
  • Include Failure-Capture Information in Exceptions

7 Refactoring API Design

Just some examples….

Effective API Design的更多相关文章

  1. API Design

    REST API Design Guidelines V 1.0.201208 Draft 5 Last Updated: 08/31/2012 1       简介 本文档旨在规范REST API的 ...

  2. Principles of good RESTful API Design 好的 RESTful API 设计

    UPDATE: This post has been expanded upon and converted into an eBook. Good API design is hard! An AP ...

  3. RESTful API Design With NodeJS & Restify

    http://code.tutsplus.com/tutorials/restful-api-design-with-nodejs-restify--cms-22637 The RESTful API ...

  4. API Design Principles -- QT Project

    [the original link] One of Qt’s most reputed merits is its consistent, easy-to-learn, powerfulAPI. T ...

  5. Atitit.index manager api design 索引管理api设计

    Atitit.index manager api design 索引管理api设计 1. kw 1 1.1. 索引类型 unique,normal,fulltxt 1 1.2. 聚集索引(cluste ...

  6. Atitit.index manager api design 索引管理api设计

    Atitit.index manager api design 索引管理api设计 1. kw1 1.1. 索引类型 unique,normal,fulltxt1 1.2. 聚集索引(clustere ...

  7. RESTful API Design: 13 Best Practices to Make Your Users Happy

    RESTful API Design: 13 Best Practices to Make Your Users Happy First step to the RESTful way: make s ...

  8. Web API design

    Web API design 28 minutes to read Most modern web applications expose APIs that clients can use to i ...

  9. Google API Design Guide (谷歌API设计指南)中文版

    面向资源的设计 这份设计指南的目标是帮助开发人员设计简单.一致.易用的网络API.同时,它也有助于收敛基于socket的API和(注:原文是with,这里翻译为“和”)基于HTTP的REST API. ...

随机推荐

  1. Qt Creater之hello world

    下载Qt Creater,博主是Qt5.2.0版本: 15:17:16 打开界面,选择文件新项目, 文件名:hellodemo: 生成的文件有.pro时项目文件,包含项目的信息,mainwindow. ...

  2. mysql 同步数据到 ElasticSearch 的方案

    MySQL Binlog 要通过 MySQL binlog 将 MySQL 的数据同步给 ES, 我们只能使用 row 模式的 binlog.如果使用 statement 或者 mixed forma ...

  3. Spring整合Quartz定时任务 在集群、分布式系统中的应用

    概述 虽然单个Quartz实例能给予你很好的Job调度能力,但它不能满足典型的企业需求,如可伸缩性.高可靠性满足.假如你需要故障转移的能力并能运行日益增多的 Job,Quartz集群势必成为你应用的一 ...

  4. tips 前端 bootstrap 嵌套行 嵌套列 溢出 宽度不正确 栅格化系统计算

    bootstrap 当嵌套列时 有时会出现很奇异的row 的width不对问题出现的情况时 <div class="row" > <!--row a--> ...

  5. 把一个IEEE754浮点数转换为IBM370浮点数的C#代码

    把一个IEEE754浮点数转换为IBM370浮点数的C#代码. 在这个网页上有古老的IBM370浮点格式的说明. // http://en.wikipedia.org/wiki/IBM_Floatin ...

  6. jQuery中下拉框select的操作方法详解

    最近在写页面的时候常常遇到要动态增删改下拉框select的情况,由于我比较习惯用jquery框架来架构我的前端js,所以就顺便把各种jquery操作下拉框select的方法总结了一下,收藏起来以便下次 ...

  7. [vmware]另类解决vmware关闭win10死机或蓝屏问题

    升级win10后在使用虚拟机发生一个问题,本人的win10版本为win10 9879, 在使用vmware时,当关机会整个系统死机,在网上搜索后发现这是由于win10内核升级导致vmware不兼容,最 ...

  8. TED_Topic5:How virtual reality can create the ultimate empathy machine

    By Chris Milk # Background about our speaker Working at the frontiers of interactive technology, Chr ...

  9. 微服务深入浅出(5)-- 声明式调用Feign

    Feign的使用 Feign采用了声明式的API接口的风格,将Java Http客户端绑定到它的内部,从而调用过程变的简单. 配置文件: spring: application: name: eure ...

  10. 蓝牙4.0 BLE入门

    在BLE协议中有两个角色,一个是周边(Periphery),另外一个是中央(Central).一个中央可以同时连接多个周边,但一个周边某一时刻只能连接一个中央.但是不管periphery还是centr ...