How to Design a Good API and Why it Matters.

[cosven]

参考资料：

• [x] http://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/32713.pdf
• [ ] https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf
• [ ] https://github.com/interagent/http-api-design

  Characteristics of a Good API

• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that use it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience

  The process of API Design

  General Principles

  API should do one thing and do it well

Funcitonality should be easy to explain

• if it's hard to name, that's generally a bad sign
• be amenable to splitting and merging modules

  API should be as small as possible but no smaller

• you can always add, but you can never remove
• look for a good power-to-weight ratio
• API should satisty it's requirements

  Implementation should not impact API

• don't let implementation details 'leak' into API
• all tuning parameters are suspect ?
• do not overspecify the behavior of methods, for example: do not specify hash functions ?

  Minimize accessibility of everything

• make classes and members as private as possible
• public classes should have no public fields ?
• allow modules to be used, understood, build, tested, and debugged independently

  Names matters - API is a little language

  Documentation matters

• documents every class, interface, method, constructor, parameter and exception

  Consider performance consequences of API desing decisions ?

  Class Design

  Minimize Mutability

• classes should be immutable unless there's a good reason to do otherwise
  • Pros: simple, thread-safe, reusable
  • Cons: separate object for each value
• if mutable, keep state-space small, well-defined

  Subclass only where is makes sense

  Design and document for inheritance or else prohibit it.

• inheritance violates encapsulation ?

  Method design

  don't make the client do anything the module could do

  don't violate the principle of least astonishment

  fail fast-report errors as soon as possible after they occur

  Provide programmatic access to all data available in string form

• otherwise, clients will parse strings, it's painful.

  use appropriate parameter and return types

• don't use string if a better type exists
• don't use floating point for manetary values
  • binary floating point causes inexact results. (Music Position use 毫秒)

    use consistent parameter ordering across methods.

• def strcpy(dest, src)
• def bcopy(dest, src, n)

  avoid long parameter lists

  avoid return values that demand exceptional processing

• return zero-length array or emtry collection, not null

  Exception Design

  Throw exceptions to indicate exceptional conditions

• don't force client to use exceptions for control flow
• conversely, don't fail silently

  Favor unchecked exceptions

  include failure-capture information in exceptions

  Refactoring API Designs