Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Golden Rules of API Design

1,781 views

Published on

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

Published in: Software
  • Login to see the comments

  • Be the first to like this

Golden Rules of API Design

  1. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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

×