Presents key points to designing a well-engineered application programming interface (API) or software library.

1. public void saveAsMidi()
{
Player player = new Player();
Pattern pattern = new Pattern("A5q B5q C5q");
try {
player.saveMidi(pattern, new File("MySong.midi"));
} catch (IOException e)
{
// handle IO Exception
}
}
public void loadAndPlayMidi()
{
Player player = new Player();
try {
player.playMidiDirectly(new File("MySong.midi"));
} catch (IOException e)
{
// handle IO Exception
} catch (InvalidMidiDataException e)
{
// handle Invalid MIDI Data Exception
}
}
public void savePattern()
{
Pattern pattern = new Pattern("A5q B5q C5q");
try {
pattern.savePattern(new File("MusicString.jfugue"));
} catch (IOException e)
{
// handle IO Exception
}
}
public void loadPattern()
{
Player player = new Player();
Pattern pattern = null;
try {
pattern = Pattern.loadPattern(new File("MusicString.jfugue"));
player.play(pattern);
Golden Rules of API Design
David Koelle
davekoelle.com
July 19, 2011

2. Objectives
• Learn guidelines for creating a solid API
• Understand the importance of API Usability
• Consider how even the best-designed API needs to
be accompanied with clear documents and guides to
succeed

3. Overview
• Background and Definitions
• The Importance of API Usability
• Guidelines for API Design
• The Importance of Effective Communication in API
Usability
• Questions and Discussion

4. Overview
• Background and Definitions
• The Importance of API Usability
• Guidelines for API Design
• The Importance of Effective Communication in API
Usability
• Questions and Discussion

5. Speaker background
• David Koelle
• First computer: TI-99/4A in 2nd grade
• Graduate of Worcester Polytechnic Institute
(Massachusetts, USA)
• 14-year career spans large and small businesses and start-ups
• Three-time Java Rock Star for talks given at JavaOne
• David has developed APIs for:
• Music Programming (JFugue)
• User Interfaces
• Graphics and Animation
• Business Intelligence
• Social Network Analysis

6. Definitions
• An Application Programming Interface (API) is
comprised of the exposed code that other
developers use to access a program’s functionality
• Examples:
• JFugue API for music programming (Java)
• Google Maps API (JavaScript, Flash, and web services)
• API Usability is a set of guidelines for creating APIs
that others can understand and use effectively

7. Definitions of usability
“Usability is how easy, efficient, and pleasant
it is to use a service”
– Jacob Nielsen
“Usability is the effectiveness, efficiency, and satisfaction
with which specified users achieve specified goals
in particular environments”
– ISO-9241 (Ergonomics of Human System Interaction)
• These definitions come from the User Interface (UI)
community, but are applicable to API Design as well!

8. Components of API Usability
• API Usability is informed by good programming
practices and user interface design
Good
Programming
Practices
User
Interface
Design
API Usability

9. Components of API Usability
• Effective communication is also an important part of
getting an API used!
Good
Programming
Practices
User
Interface
Design
API Usability
Effective
Communication

10. Good programming practices
• To design a good API, you need to use good
development practices
• A good API will follow all of the guidance in Joshua
Bloch’s book, “Effective Java”. A selection:
• Item 13: Minimize the accessibility of classes and members
• Item 38: Check parameters for validity
• Item 56: Adhere to generally accepted naming conventions
• Item 64: Strive for failure atomicity

11. User interface design
• The most important question in user interface design
is: Who is the user?
• Who are the users of an API? Other developers!
• This should be a group that’s easy for us to understand
• You could get into “personas” if you want: “Mike is a 25-
year old college graduate who learned programming in
high school and reads a lot of xkcd…”
• You also need to know: What are the user’s goals?
• What will the user try to achieve by using your API?
• How will the user measure success?
• How can you help the user succeed?

12. Four principles for highly usable systems
(D. Norman)
• Good visibility: The possible actions, the states and
the alternatives for action must be exposed
• Good conceptual model: The use of helpful,
consistent and complete abstractions helping the
users to create a proper mental image model of the
system
• Good mapping between actions and results: Natural
mapping between actions and their results
• Good feedback about results of actions: Full and
continuous feedback about the results of actions

13. Metrics for evaluating usability of a system
(B. Schneiderman)
• Time to learn a system
• Speed of task execution
• Rate of errors
• Knowledge retention over time
• Subjective user satisfaction

14. Characteristics of a good API (J. Bloch)
• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience
From Joshua Bloch’s “How to Design a Good API and Why it Matters”

15. Overview
• Background and Definitions
• The Importance of API Usability
• Guidelines for API Design
• The Importance of Effective Communication in API
Usability
• Questions and Discussion

16. Realize that publicizing an API
represents a commitment
• An API is a coding “contract”, and users of your API will
expect future versions to be compatible with released
versions
• It’s easy to add new functionality
• It’s hard to delete functionality
• This is why so many methods in the Java API are deprecated
• It’s just wrong to make a method to something
completely different between versions
• I’m glad I can’t come up with a good example for this one!
• This is the most important rule. The rest is all detail.

17. Begin with the end in mind
• Know what you want your API to achieve
• Mock up several sample applications that will use
your API before you start developing the API itself
• Develop your API using Test-Driven Development

18. Make conceptually easy things
simple to do
• Use the hidden layers of your API to offload
complexity from the end-user developer
• Example: Letting the user make an audible beep:
Bad API Good API
Open a sound data line
beep(int frequency)
Create a clip object
Generate bytes for the
frequencies
Send the clip to the data line
Close the data line
Make sure all variables are
cleaned up

19. Construct complete objects only
• Never allow a user to construct an object that is not
fully formed. Bad example:
Foo foo = new Foo();
foo.setCriticalValue(true); // This needs to be
set before the object can be used
• Two problems with this:
• Your API cannot force developers to call methods in a
predictable order
• Additional method calls require the user to learn about
those calls
• Make users think up front about what they need to
provide to create a complete object

20. Expose the minimum amount of code
• Learn how to use these Java keywords effectively:
Scope: public, private, protected (and package scope)
Modifiers: final, transient
• Using scope and modifiers properly helps users know
what they should and should not touch
• Realize that the more classes and methods you
publish, the more you’ll be accountable for in the
future

21. Be compact and concise
• Help the user derive the most benefit from the
fewest lines of code
• Example - play music in JFugue:
Player player = new Player();
player.play(“C D E F G A B”);
• Provide the smallest set of functionality in your code
that provides the most benefit
• You could write the “War and Peace” of APIs, and it might
be great, but no one would take the time to learn it all!

22. Be absolutely correct
• People rely on your API to do exactly what it says it
will do
• Make sure your API works correctly, and generates
correct output
Borrowed from Elliotte Rusty Harold’s
XOM Design Principles

23. Encode common patterns and
encourage best practices
• Notice when there code that you repeat over and
over in your sample programs
• This common pattern may be something that your users
will do, too
• Make the common code a part of your API
• Notice when you’ve identified the best way to
perform a task or achieve a goal with your API
• This may also be something your users will do
• Make the best practice a part of your API

24. Report errors immediately and clearly
• Report errors and exceptions as soon as they happen
• Guard against error-prone input by using assertions
at the beginning of a method
• Make errors as verbose as possible
• Bad example: “Can’t find file”
• Good example: “The file filename was not found in folder
folder name”

25. Overview
• Background and Definitions
• The Importance of API Usability
• Guidelines for API Design
• The Importance of Effective Communication in API
Usability
• Questions and Discussion

26. The importance of effective
communication in API Usability
• When designing an API, it’s important to use:
• Employ good programming practices
• Perform user interface design
• Now you have a quality API, and you want people to
use it. What next?
• Once the API is complete, your communication about
the API is critical to its success

27. Engage with the user community
• Allow users to communicate with you, and engage
your users in discussion
• Track requests and defects in a defect tracking
system (e.g., Google Code, Jira)
• Be responsive to email comments from users
• Publish a blog with discussions about your API
• When people contact you, ask them how they’re
using your API!
• You need to know what your users are doing, so you can
make effective changes to future versions of your API
• You may be delighted at some of the responses

28. Be open in communicating an
evolving API
• If you need to make changes to your published API,
be clear about it
• People with older versions of your API depend on
new versions acting the same way for existing
functionality

29. Provide clear support materials
• The success of your API project also depends on your
presentation of your material that markets the API:
• Documentation
• Website
• Discussion boards
• If someone goes to your webpage and can't figure
out what your API does, how to download it, how to
use it, and what some simple examples might be,
they probably won't use it

30. Finally: Delight your users
• Make sure your users enjoy using your API!
• Think of ways to make your API clever and well-
crafted
• Ensure your API anticipates the user’s needs by
providing easy access to features users want
• Prefer enjoyment through effective code as opposed
to humor in class and method names
• That comes off as a little tacky, and humor doesn’t always
translate well

31. Overview
• Background and Definitions
• The Importance of API Usability
• Guidelines for API Design
• The Importance of Effective Communication in API
Usability
• Questions and Discussion

32. Resources
• Joshua Bloch, “How to Design a Good API and Why it
Matters”
http://www.youtube.com/watch?v=aAb7hSCtvGw
• Joshua Bloch, “Effective Java”
http://www.amazon.com/Effective-Java-2nd-Joshua-Bloch/dp/0321356683
• Bill Venners, “API Design with Java”
http://www.artima.com/apidesign/
• Five-part discussion with Bill Venners and Elliotte Rusty
Harold on API design for JDOM and XOM
Part 5: http://www.artima.com/intv/xomdesign.html
• Jaroslav Tulach, “Practical API Design” (Apress)
http://www.apress.com/9781430209737

33. public void saveAsMidi()
{
Player player = new Player();
Pattern pattern = new Pattern("A5q B5q C5q");
try {
player.saveMidi(pattern, new File("MySong.midi"));
} catch (IOException e)
{
// handle IO Exception
}
}
public void loadAndPlayMidi()
{
Player player = new Player();
try {
player.playMidiDirectly(new File("MySong.midi"));
} catch (IOException e)
{
// handle IO Exception
} catch (InvalidMidiDataException e)
{
// handle Invalid MIDI Data Exception
}
}
public void savePattern()
{
Pattern pattern = new Pattern("A5q B5q C5q");
try {
pattern.savePattern(new File("MusicString.jfugue"));
} catch (IOException e)
{
// handle IO Exception
}
}
public void loadPattern()
{
Player player = new Player();
Pattern pattern = null;
try {
pattern = Pattern.loadPattern(new File("MusicString.jfugue"));
player.play(pattern);
Thank You!
David Koelle
davekoelle.com
July 19, 2011