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.

Your API is a UI


Published on

Whether you're creating a complex web application or a simple library, everything you create has a user. Why, then, do we concentrate on our users when developing a user interface, but so often forget them when developing APIs? In this talk, Christopher presents a whirlwind overview of a variety of different User Experience considerations when designing your APIs.

Published in: Software
  • Login to see the comments

Your API is a UI

  1. 1. Your API is a UIChristopher Hoult
  2. 2. Your API is a UI @choult Who is this guy? “We’re Hiring” Previously...
  3. 3. I also act Credit: Richard Brown
  4. 4. YMMV
  5. 5. Your API is a UI @choult What is a UI? A “space where interactions between humans and machines occur. The goal of this interaction is effective operation and control of the machine on the user’s end, and feedback from the machine, which aids the operator in making operational decisions.” Wikipedia
  6. 6. Your API is a UI @choult What is an API? “An application programming interface (API) specifies a software component in terms of its operations, their inputs and outputs and underlying types. Its main purpose is to define a set of functionalities that are independent of their respective implementation, allowing both definition and implementation to vary without compromising each other.” Wikipedia
  7. 7. Users
  8. 8. Your API is a UI @choult Who are your users? • Developers • Colleagues • Customers • Their Customers • Applications
  9. 9. Your API is a UI @choult What does your API do? • Real use cases • User stories • Document usage/flow • Sell your API
  10. 10. Your API is a UI @choult What can users do? • Why are you exposing an API? • It’s very rare to expose everything • Too much complexity -> confusion • Define restrictions • Validate user stories against goals
  11. 11. Your API is a UI @choult API Hierarchy of Needs
  12. 12. Usability
  13. 13. Your API is a UI @choult Consistency • Improves comfort for user • Style guide (PSR-1/2; REST etc.) • Common attributes/functions • Naming • Error codes
  14. 14. Your API is a UI @choult Patterns • Users understand Patterns • Patterns aid understanding • Webservices: RPC, REST • Code: Gang of Four etc.
  15. 15. Your API is a UI @choult Information Hierarchy • Define ERM • Arrange entry points from user POV • Nesting entities can be problematic • Get it right: classes and objects intuitive
  16. 16. Your API is a UI @choult Abstraction • User stories guide API design • Hide complexity • Avoid adhering to underlying model • Do the hard work so users don’t have to
  17. 17. Your API is a UI @choult Simplicity • Best result of abstraction • More straightforward, more use • Smaller footprint = fewer failure paths • Easy fault detection
  18. 18. Your API is a UI @choult Extensibility • Flipside to abstraction • How will users extend codebase? • Restrict as required - public/protected/private • Take care - hard to retract public • Patterns help here!
  19. 19. Functionality & Reliability (Oh, so he does do colour!)
  20. 20. Your API is a UI @choult Testing • Use appropriate testing methodology • Make part of build/release process • Monitor production with live testing • Consider record/replay testing • Regression testing
  21. 21. Your API is a UI @choult Metrics • Metrics tell you what is happening • Record status codes • Calibrate with normal running • Insight into running code • Graphite/statsd
  22. 22. Your API is a UI @choult Logging • Tells you what happened • Helps debug production faults • Reference in error messages • Insight into running applications • Information for users of code
  23. 23. Your API is a UI @choult Versioning • Plan versioning upfront • Define upgrade/deprecation strategy • What is a breaking change? • How long will API be supported? • Communicate with users
  24. 24. Your API is a UI @choult Feedback • Clear feedback • Reasons for failure • Appropriate language • Error codes • Normalized; human readable • Provide glossary
  25. 25. Proficiency
  26. 26. Your API is a UI @choult Documentation • No such thing as “self-documenting code” • Write fulsome documentation • Include working examples • Cross-link from code • Manuals, Quick Start Guides, Cookbooks
  27. 27. Your API is a UI @choult Living Documentation • Docblocks (Javadoc/PHPdoc) are a good start • Cross-language (eg Doxygen) • Use standards like PSR 5 • Annotations • Interactive documentation - eg. IODocs
  28. 28. Your API is a UI @choult Support / Community • Define channels of communication • Define location for participation • Invite feedback • Invite contribution - define guidelines • Respond gracefully and attentively • Learn from your users
  29. 29. Creativity
  30. 30. Your API is a UI @choult <Inspirational Title> • Flexibility • Extensibility • Serendipity • Outreach • Encouragement
  31. 31. Pragmatism
  32. 32. Your API is a UI @choult On Pragmatism • Pragmatism is good! • Can promote technical debt • Find a balance - RESTlike, RPCish • Be realistic • Iterate - versioning and deprecation
  33. 33. Take Pride
  34. 34. Your API is a UI @choult Your API is You! • Like your UI, your API is your public face • It is your avatar • Take pride in your work • Impress your users with its awesomeness!
  35. 35. Questions?
  36. 36. Your API is a UI @choult Thank you! @choult christopherhoult This presentation was typeset in HandTIMES and Open Sans, using Adobe InDesign CS6 (because I’m a lunatic) Feedback please!
  37. 37. Your API is a UI @choult Resources / Inspiration 10 User Interface Design Fundamentals - Kyle Sollenberger APIUX: API Hierarchy of Needs 5 Golden Rules for Great Web API Design - Jordan Ambra