API

API, stands for application programmable interface. It is an interface, a boundary between external programmable activity and the internal components. Every API has these few definition:

• WHAT is it for
• WHERE should the data flow (One-way, Two-way, into API, out from API)
• WHO should handle the API call

It is applicable at library, framework, and even application levels.

Good Vs. Bad APIs

1. DO what you say you do
2. FOLLOW language- and platform-dependent convention (typographical and grammatical)
3. USE clear, specific naming convention
4. BE consistent
5. MINIMIZE mutability

Characteristic of GOOD API

1. Easy to learn
2. Easy to use, even without documentation
3. Hard to misuse
4. Easy to read and maintain code that uses it
5. Sufficiently powerful to satisfy requirements
6. Easy to extend
7. Appropriate to audience

When to Use (Problem)

• When the problem requires one to declare definitive interface for external users to interact with the components
• When encapsulation is a requirement to protect the internal intellectual executions.
• When there is a demand for a programmable interface instead of graphical interface.
• When the problem requires standardized releases of interfaces.

Example (Solution)

Designing API can be a dreadful job. First, let us look at the golden rules:

Design Golden Rules

1. Good APIs are great assets
   • Distributed developments among many teams
   • Promotes incremental, non-linear software development
   • Facilitates communications
   • Long-term buy-in from client & customers
2. Poor APIs are a great liability
   • Lost productivity from your software developers
   • Wasted customer supports and resources
   • Lack of buy-in from client & customers
3. ONE chance to get it right
   • You CAN only ADD and VIEW (USE)
     1. Consider learning weight (how many API to learn / how hard to use API before one can use)
     2. Apply principle of universal design
        • Equitable use
        • Flexibility in use
        • Simple and intuitive use
        • Perceptible information
        • Tolerance for error
        • Low physical effort
        • Size and space for approach and use
   • You CANNOT UPDATE (alter parameters, I/O requirements etc) and DELETE
     1. When in doubt, leave it out!
     2. Minimize accessibility until tested and verified necessary.
     3. Prevent leaks of implementation details
4. Use accessor methods, preferably interface over abstract classes.
   • Make use of factory methods pattern
5. Most API designs are over-constrained
   • You can't please everyone.
   • Expect mistakes.

Design Process

1. Define the API scope
   • Collect use-cases stories and define the requirements (Often, you'll get proposed solution instead of pro-actively design)
   • Can be easier and more rewarding to build something more general
   • Be very skeptical
     1. Distinguish true requirements from so called solutions
     2. When in doubt, leave it out.
2. Draft specification
   • Keep it simple and short for easier modifications
   • Agile trumps completeness
3. Build a prototype
   • Code early, code often
   • Start before you implement the API
   • Start before you even specify it properly
   • Prevent nasty surprises so code lives on as examples, unit tests
   • Be amendable to splitting and merging modules
4. Test it out internally and gather feedback from users
   • Bounce spec off as many people as possible
5. Revise and repeat
   • If you write one, it probably won't support another.
   • If you write two, it will support with difficulty.
   • If you write three, it will work fine.
6. Document the API - Integral to the design and development process
   1. API should be self-documenting
   2. Good names drive good design
      • If it is hard to name, that is bad design
   3. Document religiously
      1. All public classes
      2. All public methods
      3. All public fields
      4. All method parameters
      5. Explicitly write behavioral specifications
   4. DO NOT document implementation details

Design Patterns

1. Minimize Mutability
   • Advantages: simple, thread-safe, reusable
   • Disadvantage: separate object for each value
2. Subclass Only When Making Sense
   • Public class should not subclass other public classes for ease of implementation
3. Design and Document Inheritance; Prohibits otherwise
   • Inheritance violates encapsulation.
4. DO NOT make client do anything module can do
   • Reduce the needs of boilerplate - Ugly, annoying, and error-prone
5. Fail Fast
6. Provide Pragmatic Access to All Data Available in String Form
   • Otherwise parsing string is very painful for client
7. Overload with care
   1. Avoid ambiguous overloading
   2. If you need, ensure it produces the same behavior for same arguments
8. Use Appropriate Parameters and Return Types
   1. Favor interface over classes
   2. Use most specific input parameter type
   3. DO NOT use string if better exists
   4. DO NOT use floating point for monetary values
   5. Use DOUBLE (64-bit) instead of FLOAT (32-bit)
      1. Precision loss is real; performance loss is negligible
9. Avoid Long Parameter List
   1. Stay consistent with name
   2. Fewer the better
      1. Client need to refer to docs - reduce learning loads
10. Avoid return values that demands exceptional processing
    1. Return empty value, not nil
11. Throw exception to indicate exceptional conditions
    1. Don't force client to use exceptions control flow
    2. Don't fail silently
12. Favor Unchecked Exception
    1. Checked - client must recover
    2. Unchecked - programming error
    3. Overuse of checked exception - boilerplate (Bad)
13. Include failure-capture information in exception

Expected Outcome (Consequences)

1. Components can be interfaced via programmable interactions.