Application Programming Interface (API)

Good API requirements:

• Easy to learn and use, even without documentation. Don't Violate the Principle of Least astonishmen.
• Hard to misuse.
• Powerful and easy to extend.
• Easy to use than re-implement equal functionality.
• Consistent.
• Abstract interface that does not limit performance and scaling.

中心原则是，先写使用API的代码，然后再写实现它们的代码。因为，如果实现代码被废弃，之前的工作就都白做了。事实上，应该在给出设计规范前写API的代码，否则你可能把时间浪费在给最后完全不需要的东西设计规范上。

不用API写代码，就不可能看出API有什么问题。

说到能够运行的最简程序，我完全赞同这种提法。API设计有一条基本原则：疑则不用。它必须是完全满足你关心的所有用例的最简系统。而不是说“把乱七八糟的代码堆在一起”。有很多格言警句说明了这点。我最喜欢的一条是：”简单没那么容易做到。“

-- Joshua Bloch

Interface must be independent of implementation.

• Implementation details confuse users.
• What is implementation detail?
• All tuning parameters are suspect.
• On-disk or on-the-wire formats.
• Exceptions.

Minimize accessibility of everything: information hiding.

API names matter: API is a little language.

Documentation matters.

Reuse is something that is far easier to say than to do. Doing it requires both good design and very good documentation. Even when we see good design, which is still infrequently, we won't see the components reused without good documentation.

-- D. L. Parnas, _Software Aging. Proceedings of 16th International Conference Software Engineering, 1994

API should do one thing and do it well.

• If it's hard to name, that generally a bad sign.

API should be as small as possible, but no smaller.

• When in doubt, leave it out: you can always add, but never remove.

Performance and scaling:

• Make things immutable or document them to be immutable.
• Account for concurrency that are not threads for processes.
• Be reentrant.

Default values matters.

Consistent parameters:

• Ordering of parameters is important.
• What you are operating on should always the first parameter.
• Similar methods should have same ordering of parameters and types.
• If the order is the wrong way around, stick with it! Consistency is more important.

Avoid long parameter lists:

• Three or fewer parameters is ideal: more and users will have to refer to docs.
• Long lists of identically typed params harmful:
  • Programmers transpose parameters by mistake.
  • Programs still compile, run, but misbehave!
• Two techniques for shortening parameter lists:
  • Break up method
  • Create helper class to hold parameters

Use data structures but not strings:

• If users have to parse return values of APIs, you are doing something wrong.
• It's even worse to turn string format into de facto API.
• If a implementation detail becomes an interface, it prevents future improvements.

The best part for strings is: clients don't need a SDK.

Avoid return values that demand exceptional processing.

• Return only one data type.
• Return zero-length array or empty collection, not null.

Fail fast – report errors as soon as possible after they occur.

Raise exception on error and return result. If no return value is needed, return null. Don't mix result and error message in return value.

Throw exceptions to indicate exceptional conditions.

• Don’t force client to use exceptions for control flow.
• Conversely, don’t fail silently.

Favor unchecked exceptions.

• Checked – client must take recovery action
• Unchecked – programming error
• Overuse of checked exceptions causes boilerplate

Include failure-capture information in exceptions.

• Allows diagnosis and repair or recovery.
• For unchecked exceptions, message suffices.
• For checked exceptions, provide accessor.