Practical API Design

Practical API Design

by Jaroslav Tulach
Released June 2008
Publisher(s): Apress
ISBN: None

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

You might think more than enough design books exist in the programming world already. In fact, there are so many that it makes sense to ask why you would read yet another. Is there really a need for yet another design book? In fact, there is a greater need than ever before, and Practical API Design: Confessions of a Java Framework Architect fills that need!

  • Teaches you how to write an API that will stand the test of time
  • Written by the designer of the NetBeans API at Sun Technologies
  • Based on best practices, scalability, and API design patterns

Table of contents

  1. Cover
  2. Title
  3. Copyright
  4. Contents at a Glance
  5. Contents
  6. About the Author
  7. Acknowledgments
  8. Prologue: Yet Another Design Book?
  9. Part 1: Theory and Justification
    1. Chapter 1: The Art of Building Modern Software
      1. Rationalism, Empiricism, and Cluelessness
      2. Evolution of Software So Far
      3. Gigantic Building Blocks
      4. Beauty, Truth, and Elegance
      5. More Cluelessness!
    2. Chapter 2: The Motivation to Create an API
      1. Distributed Development
      2. Modularizing Applications
        1. Nonlinear Versioning
      3. It’s All About Communication
      4. Empirical Programming
      5. The First Version Is Always Easy
    3. Chapter 3: Determining What Makes a Good API
      1. Method and Field Signatures
      2. Files and Their Content
      3. Environment Variables and Command-Line Options
      4. Text Messages As APIs
      5. Protocols
      6. Behavior
      7. I18N Support and L10N Messages
      8. Wide Definition of APIs
      9. How to Check the Quality of an API
        1. Comprehensibility
        2. Consistency
        3. Discoverability
        4. Simple Tasks Should Be Easy
        5. Preservation of Investment
    4. Chapter 4: Ever-Changing Targets
      1. The First Version Is Never Perfect
      2. Backward Compatibility
        1. Source Compatibility
        2. Binary Compatibility
        3. Functional Compatibility—the Amoeba Effect
      3. The Importance of Being Use Case Oriented
      4. API Reviews
      5. Life Cycle of an API
      6. Incremental Improvements
  10. Part 2: Practical Design
    1. Chapter 5: Do Not Expose More Than You Want
      1. A Method Is Better Than a Field
      2. A Factory Is Better Than a Constructor
      3. Make Everything Final
      4. Do Not Put Setters Where They Do Not Belong
      5. Allow Access Only from Friend Code
      6. Give the Creator of an Object More Rights
      7. Do Not Expose Deep Hierarchies
    2. Chapter 6: Code Against Interfaces, Not Implementations
      1. Removing a Method or a Field
      2. Removing or Adding a Class or an Interface
      3. Inserting an Interface or a Class into an Existing Hierarchy
      4. Adding a Method or a Field
      5. Comparing Java Interfaces and Classes
      6. In Weakness Lies Strength
      7. A Method Addition Lover’s Heaven
      8. Are Abstract Classes Useful?
      9. Getting Ready for Growing Parameters
      10. Interfaces vs. Classes
    3. Chapter 7: Use Modular Architecture
      1. Types of Modular Design
      2. Intercomponent Lookup and Communication
      3. Writing an Extension Point
      4. The Need for Cyclic Dependencies
      5. Lookup Is Everywhere
      6. Overuse of Lookup
    4. Chapter 8: Separate APIs for Clients and Providers
      1. Expressing API/SPI in C and Java
      2. API Evolution Is Different from SPI Evolution
      3. Writer Evolution Between Java 1.4 and 1.5
      4. Split Your API Reasonably
    5. Chapter 9: Keep Testability in Mind
      1. API and Testing
      2. The Fade of the Specification
      3. Good Tools Make Any API Easier
      4. Test Compatibility Kit
    6. Chapter 10: Cooperating with Other APIs
      1. Beware of Using Other APIs
      2. Leaking Abstractions
      3. Enforcing Consistency of APIs
      4. Delegation and Composition
      5. Prevent Misuses of the API
      6. Do Not Overuse the JavaBeans Listener Pattern
    7. Chapter 11: Runtime Aspects of APIs
      1. Fixing Odyssey
      2. Reliability and Cluelessness
      3. Synchronization and Deadlocks
        1. Document the Threading Model
        2. Pitfalls of Java Monitors
        3. Deadlock Conditions
        4. Deadlock Test
        5. Testing Race Conditions
        6. Analyzing Random Failures
        7. Advanced Usage of Logging
        8. Execution Flow Control Using Logging
      4. Preparing for Reentrant Calls
      5. Memory Management
    8. Chapter 12: Declarative Programming
      1. Make Objects Immutable
      2. Immutable Behavior
      3. Compatibility of Documents
  11. Part 3: Daily Life
    1. Chapter 13: Extreme Advice Considered Harmful
      1. An API Must Be Beautiful
      2. An API Has to Be Correct
      3. An API Has to Be Simple
      4. An API Has to Have Good Performance
      5. An API Must Be 100 Percent Compatible
      6. An API Needs to Be Symmetrical
    2. Chapter 14: Paradoxes of API Design
      1. API Doublethink
      2. The Invisible Job
      3. Overcoming the Fear of Committing to a Stable API
      4. Minimizing Maintenance Cost
    3. Chapter 15: Evolving the API Universe
      1. Resuscitating Broken Libraries
      2. Conscious vs. Unconscious Upgrades
      3. Alternative Behavior
      4. Bridges and the Coexistence of Similar APIs
    4. Chapter 16: Teamwork
      1. Organizing Reviews Before Committing Code
      2. Convincing Developers to Document Their API
      3. Big Brother Never Sleeps
      4. Accepting API Patches
    5. Chapter 17: Using Games to Improve API Design Skills
      1. Overview
      2. Day 1
        1. Problem of Nonpublic API Classes
        2. The Immutability Problem
        3. The Problem of the Missing Implementation
        4. The Problem of Possibly Incorrect Results
        5. Solutions for Day 1
      3. Day 2
        1. I Want to Fix My Mistakes Problem
        2. Solutions for Day 2
      4. Day 3: Judgment Day
        1. Conclusions
      5. Play Too!
    6. Chapter 18: Extensible Visitor Pattern Case Study
      1. Abstract Class
      2. Preparing for Evolution
      3. Default Traversal
      4. Clean Definition of a Version
      5. Nonmonotonic Evolution
      6. Data Structure Using Interfaces
      7. Client and Provider Visitors
      8. Triple Dispatch
      9. A Happy End for Visitors
      10. Syntactic Sugar
    7. Chapter 19: End-of-Life Procedures
      1. The Importance of a Specification Version
      2. The Importance of Module Dependencies
      3. Should Removed Pieces Lie Around Forever?
      4. Splitting Monolithic APIs
  12. Epilogue: The Future
    1. Principia Informatica
    2. Cluelessness Is Here to Stay
    3. API Design Methodology
    4. Languages Ready for Evolution
    5. The Role of Education
    6. Share!
  13. Bibliography
  14. Index

Product information

  • Title: Practical API Design
  • Author(s): Jaroslav Tulach
  • Release date: June 2008
  • Publisher(s): Apress
  • ISBN: None