Scribd Logo
Upload

Welcome to Scribd!

  • 527 views

    Practical API Design

    Uploaded by

    tneogi
    This document discusses best practices for designing application programming interfaces (APIs). It recommends that APIs be use case driven, consistent in design, and simple with only necessary functionality exposed. The document emphasizes designing for evolution and future changes while maintaining backward compatibility. It introduces the "amoeba model" for evaluating API quality based on how well the code matches its specifications over time. The presentation also describes an "API fest" for practicing agile and evolutionary API design.

    Copyright:

    Attribution Non-Commercial (BY-NC)
    Download as PDF, TXT or read online from Scribd

    Practical API Design

    Uploaded by

    tneogi
    527 views18 pages
    This document discusses best practices for designing application programming interfaces (APIs). It recommends that APIs be use case driven, consistent in design, and simple with only necessary functionality exposed. The document emphasizes designing for evolution and future changes while maintaining backward compatibility. It introduces the "amoeba model" for evaluating API quality based on how well the code matches its specifications over time. The presentation also describes an "API fest" for practicing agile and evolutionary API design.

    Copyright

    © Attribution Non-Commercial (BY-NC)

    Available Formats

    PDF, TXT or read online from Scribd

    Did you find this document useful?

    Is this content inappropriate?

    This document discusses best practices for designing application programming interfaces (APIs). It recommends that APIs be use case driven, consistent in design, and simple with only necessary functionality exposed. The document emphasizes designing for evolution and future changes while maintaining backward compatibility. It introduces the "amoeba model" for evaluating API quality based on how well the code matches its specifications over time. The presentation also describes an "API fest" for practicing agile and evolutionary API design.

    Copyright:

    Attribution Non-Commercial (BY-NC)
    Download as PDF, TXT or read online from Scribd
    Download as pdf or txt
    527 views18 pages

    Practical API Design

    Uploaded by

    tneogi
    This document discusses best practices for designing application programming interfaces (APIs). It recommends that APIs be use case driven, consistent in design, and simple with only necessary functionality exposed. The document emphasizes designing for evolution and future changes while maintaining backward compatibility. It introduces the "amoeba model" for evaluating API quality based on how well the code matches its specifications over time. The presentation also describes an "API fest" for practicing agile and evolutionary API design.

    Copyright:

    Attribution Non-Commercial (BY-NC)
    Download as PDF, TXT or read online from Scribd
    Download as pdf or txt
    of 18

    Practical API Design

    ● Jaroslav Tulach
    ●

    Sun Microsystems
    http://www.netbeans.org

    JUG 2007 Praha


    Agenda

    What makes good API?


    Like a free speech
    Examples
    Q&A
    What makes an API good?

    • API is used for communication


    > build trust, clearly describe plans

    • Must be:
    > a) beautiful
    > b) correct
    > c) simple
    > d) good performance
    • Not necessarily!

    http://apidesign.org
    What makes a technology good?

    • Coolness
    > before adoption
    • Time to market
    > at beginning of adoption
    • Total Cost of Ownership
    > then and forever

    http://apidesign.org
    API is a technology facade

    • Hype & Community


    • Limited understanding
    • Empiristic programming
    > Cluelessness
    • Error forgiving
    • Easy upgradability

    http://apidesign.org
    Rules for Successful API design

    • Use case driven API design


    > use cases -> scenarios -> javadoc

    • Consistent API design


    > An interface that is predictable serves better than one which is
    locally optimal but inconsistent across the whole set.
    • Simple and clean API design
    > less is more - expose only necessary functionality

    • Think about future evolution


    > First version is not going to be perfect
    Like Human Rights

    What is the most important right?

    The right for free speech. Because if you have


    right to speak freely, you can always talk
    about the missing ones and ask for them.

    Karel Havlíček Borovský

    http://apidesign.org
    Evolution

    • First version is insufficient


    • Incremental changes
    • Knowing your clients is not possible
    • Preservation of Investments
    • Agile API Design

    http://apidesign.org
    Backward Compatibility

    • Source
    > ability to compile against new version
    • Binary
    > ability to link to new version
    • Functional
    > ability to compute the same result

    http://apidesign.org
    Evaluation of an API Quality

    • Customer centric – easy to use


    • Use cases, scenarios, javadoc
    • Future evolution
    • Test coverage
    • quality = code Δ specification
    • the "amoeba" model

    http://apidesign.org
    The Amoeba Model

    http://apidesign.org
    The Amoeba Model

    http://apidesign.org
    The Amoeba Model

    http://apidesign.org
    API Fest

    • Agile to ad-absurdum
    • Only about evolution
    • Not a beauty contest
    • Evaluated by you

    http://apidesign.org
    API Fest '08 Roadmap

    • Solutions for Task 1 arrived


    > need to align
    • Additional 2-5 rounds
    > once, twice a week
    • Judgment Day
    • Finish by Oct 23, 2008

    http://apidesign.org
    API Fest Don'ts

    • Do not fix previous mistakes


    > usually leads to incompatibilities
    • Runtime aspects are important
    • Do not remove anything from the API
    • Add carefully
    > new class/interface is OK
    > new method in subclassable type is not OK

    http://apidesign.org
    API Fest Gotchas

    • Seeking for evolution problems with God's eyes


    > knowing all the previous versions
    > line by line diffs
    • No permissions, please
    > no reflection
    > no getClass().getName()

    http://apidesign.org
    Questions & Answers
    Practical API Design
    Confessions of a Java Framework Architect
    ISBN-10: 1430209739

    Jaroslav Tulach
    http://www.apidesign.org

    You might also like