Golden Rules of API Design

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); } catch (IOException e) { // handle IO Exception } }

Golden Rules of API Design

David Koelledavekoelle.com

July 19, 2011

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

Overview

• Background and Definitions• The Importance of API Usability• Guidelines for API Design• The Importance of Effective Communication in API

Usability• Questions and Discussion

Overview



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

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

Definitions of usability

“Usability is how easy, efficient, and pleasantit 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!

Components of API Usability

• API Usability is informed by good programming practices and user interface design

Good Programming

Practices

User Interface

Design

API Usability

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

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

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?

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

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

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”

Overview



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.

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

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 APIOpen a sound data line

beep(int frequency)

Create a clip objectGenerate bytes for the frequencies

Send the clip to the data lineClose the data line Make sure all variables are cleaned up

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

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

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!

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

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

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”

Overview



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

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

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

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

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

Overview



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 XOMPart 5: http://www.artima.com/intv/xomdesign.html

• Jaroslav Tulach, “Practical API Design” (Apress)http://www.apress.com/9781430209737

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); } catch (IOException e) { // handle IO Exception } }

Thank You!

David Koelledavekoelle.com

July 19, 2011

Software

Golden Rules of API Design