Designing Usable APIs featuring Forrester Research, Inc.


Published on

Deliver a Great Developer Experience (DX) as Part of an Effective API Strategy


Designing a great enterprise API is not easy. Exposing an interface is relatively simple but API designers have a great deal more to think about – business models, process context, transactional integrity, privacy concerns, data ownership… the list goes on.

For enterprise API designers, a clear focus on developer experience (DX) is often the best way to get things moving in the right direction. Creating an API that developers love to use will produce a wealth of benefits for any API program, such as:

Increasing API adoption rates
Reducing implementation costs
Ensuring the program is aligned with core business goals
Join this webinar with Ronnie Mitra of Layer 7 and guest speaker Randy Heffner of Forrester Research, Inc. to get practical tips on building APIs that will provide a great DX and truly contribute to your organization’s business success.

You Will Learn

What the term “well-designed API” means, in practical terms
Why developer experience matters and how it aligns with business goals
How to make rational design choices that will improve DX

Presented By

Ronnie Mitra
Principal API Architect, Layer 7

Guest Speaker

Randy Heffner
VP, Principal Analyst, Forrester Research, Inc.

Published in: Technology

Designing Usable APIs featuring Forrester Research, Inc.

  1. 1. Designing Usable APIs Ronnie Mitra @mitraman Randy Heffner @biztech21
  2. 2. Webinar Housekeeping Questions -Chat any questions you have and we’ll answer them at the end of this webinar Twitter - Today’s event hashtag: #L7webinar Follow us on Twitter: @layer7 @mitraman @forrester @biztech21
  3. 3. The Keys To Well-Designed APIs Randy Heffner, Vice President & Principal Analyst November 6, 2013
  4. 4. Enterprises are deep into APIs
  5. 5. Sample business goals for external APIs Customer service Process optimization Allow customers to directly manipulate account and order information (Saxo Bank, Optify) Create end-to-end monitored process flow across customers and partners (Con-Way Freight) Market mindshare Channel enablement Let partners seamlessly embed your business into their offerings (Amazon store, Sears) Provide useful data that people can build into consumer-facing apps (USA Today, Yellow Pages) White-label your business Build volume by letting others sell your products as their own (Travelocity, Expedia)
  6. 6. Strong API design: Five major areas API categories • Based on business context of API use and design API types • Function, purpose, architecture context Interface technical design • Messaging style, request structure, payloads, quality of service Community concerns • Effect of API limits, testing, support Future preparation • Open-ended design, portfolio management © 2013 Forrester Research, Inc. Reproduction Prohibited 6
  7. 7. Business context sets API category Wide-open to innovation Tech-savvy consumers Web site developers Value-add innovators Digital disruptors Digital experiences (mobile, web, etc.) Optimized business Build product ecosystems Enterprise customers Distribution partners 1 Enterprise customers Suppliers 2 Open web APIs Tech-savvy consumers Product ecosystem 4 B2B APIs Product APIs Products 3 Internal APIs (software, physical products, services) Enterprise applications (custom, off-the-shelf, cloud, on-premise) Your enterprise Your products
  8. 8. Purpose and function drive API types Data APIs • Play in the data economy • Direct entity/collection access Transaction APIs • Complex, multiple resource interactions • Push processes forward Integration APIs • Technical connections between siloed applications User interface APIs Application component APIs Utility APIs © 2013 Forrester Research, Inc. Reproduction Prohibited • Serve UI fragments and fully-formed UI components • Provide business function support • Technical support, such as security, logging, and format conversion 8
  9. 9. Mobile needs multiple API types UI User interface APIs Local / cached data Device UI-level APIs Data APIs API façade for core transactions UI logic Mobile backend Transaction APIs Local / cached data Core SOA business transactions Core systems
  10. 10. REST vs SOAP: Watch out for religion Which of the following architecture styles does your organization currently use or plan to use? Implemented, not expanding No plans Implemented, expanding Decreasing or removing Service-oriented architecture APIs exposed internally 18% 26% 14% SOAP-based services Message-oriented middleware 19% 15% Planning to implement Don't know/N/A 7% 27% 7% 25% 1% 23% 26% 1% 25% Net expansion audience 33% 33% 15% 4% 30% 3% 30% 16% 18% 33% 1% 29% 21% 3% 27% 19% APIs exposed externally 8% 16% 6% RESTful services 6%11% 4% 4% 40% 40% 1% 38% 15% Note: Net expansion audience = “implemented, expanding” + “planning to implement” – “decreasing or removing” Base: 368 Professional Developers, IT Developers, Consultants that work for organizations with 1,000+ employees Source: Forrsights Developer Survey, Q1 2013
  11. 11. Messaging types vary on reach, QoS Messaging type Reach Quality of service (QoS) Free-form REST Any API category; especially important for open Web Custom configuration of open standards; validation limited with JSON Free-form REST with hypermedia Any API category; higher skill requirement limits audience Custom configuration of open standards; validation limited with JSON Structured REST (e.g., OData) May need to hide formal structure to gain broad reach Standardized patterns based on open standards; defined types support validation of JSON SOAP Internal APIs; some B2B APIs; very few open Web APIs Strong validation, standards for security, federation, reliable messaging, and attachments Message-oriented (e.g., JMS) Internal APIs; very limited B2B APIs Transactional messaging; validation with XML payload
  12. 12. Alternate API types fit special contexts JavaScript APIs • UI development (Twitter Embedded Timeline) Language bindings (i.e., SDKs) • Natural programming constructs • Can layer on top of API-based services (Box) RSS and Atom • Good for periodic info distribution Streaming API • Good for continuous info distribution (E*Trade) Special cases • XMPP for bioinformatics • Ford OpenXC  USB, Bluetooth © 2013 Forrester Research, Inc. Reproduction Prohibited 12
  13. 13. REST: Design for comprehensibility Encryption With open HTTP, assume that credentials will be stolen Domain name Keep domain names stable; may be useful for grouping or macro-level routing URI: encryption domain name URI path query string URI path Resources are all the rage, but functions (actions) are sometimes more clear, direct, and comprehensible; additional path nodes may add clarity through structure Query string Allow simple, straightforward options, but don’t use it to introduce whole new API functions
  14. 14. Simple if can be, complex if need be JSON: Fast becoming preferred on the open Web XML: Benefits for validation and vertical industries XHTML: Benefits for validation and web app support Zip: Smaller payloads; less reach Payload: JSON | XML | XHTML | ZIP | others no links | links as HTML relations | links as payload data | others In-payload: Greater programming flexibility <rel>: Provides for parsing for a specific link type No links: Simplest for reach to a broad audience
  15. 15. REST verbs: Not as clear as you think HTTP verb: GET | POST | PUT | DELETE | HEAD | OPTIONS | PATCH Q: Which is the correct handling of “POST /order”? A) Store a new order record — AND submit the order for processing B) Store a new order record — DO NOT submit the order for processing C) Store a new order record — DO submit IF orderStatus = “submit” D) Store a new order record ONLY if it passes validation A: Whatever it says in the documentation The lesson: REST is clear only in your documentation
  16. 16. REST attachments: No easy way URI reference • Simplest, but must have Internet address • Separate calls for each attachment Binary in the payload • Single request • Larger message size • Nontrivial for API users and providers Separate attachment API • Clarity on media types • Separate calls for each attachment • No place for metadata upon retrieval Multipart messages © 2013 Forrester Research, Inc. Reproduction Prohibited • Single request; best efficiency • More difficult to program 16
  17. 17. One way or the other, plan for versioning URI: Early, for API “family” management URI: Late, for API independence URI: Query string, to make it optional – Danger Zone Gotta have a good reason: In the domain name: . . As a custom media type: application/x-customerV1 In the request payload: { “version": “v1", . . . } As an HTTP port number: . .
  18. 18. API security: Know your scenarios Scenario Top approaches Open Web partnering You own the data and want to expand market presence • API key • Digital signature Open Web customer integration Customers own the data • API key • OAuth B2B process APIs You and/or partners own the data • Two-way SSL • Federated identity (SAML, OpenID Connect) B2B service provider APIs Your partners’ or customers’ stakeholders own the data • OAuth • Federated identity • Two-way SSL Internal APIs You alone handle the data • Wide latitude • SOA security as strong foundation © 2013 Forrester Research, Inc. Reproduction Prohibited 18
  19. 19. API design recommendations › Start with your business purpose and audience › Favor REST for external reach; don’t fear SOAP › With REST, assume nothing in your docs › Decide how open-ended to be: • Data (resource) APIs support an open-ended future • Transaction (function or action) APIs provide better protection for business integrity • Query parameters enable special functions © 2013 Forrester Research, Inc. Reproduction Prohibited 19
  20. 20. Thank you Randy Heffner @BizTech21
  21. 21. Ronnie Mitra
  22. 22. API Program Challenges Big Questions: - How do we align with strategic goals? - What should the API look like? - What message formats ? Which style? What protocol? - What API style? ?
  23. 23. How do you design an API? 1. Identify resources bushels 2. Design URIs /bushel/apples 3. Define operations GET apples /bushel/apples This is not enough!
  24. 24. What is Developer Experience (DX)?  Developers are the users of an API  User Experience (UX) for an API = Developer Experience (DX)  The DX is a measure of how the API makes developers feel
  25. 25. Partner API DX Positive Feelings Safety Trust Empowerment Amazement Eagerness Pride Familiarity Inspired Negative Feelings Confusion Mistrust Isolation Anger Embarrassment Abandonment Frustration Neglected
  26. 26. A DX Focus Aligns with Strategic Goals Increased Growth • Market Differentiation • Increased “stickiness” • Word of mouth advertising Reduced Cost • Reduced learning curve • Harder to make mistakes • Better engagement level
  27. 27. Driving Positive Experiences Category Examples and Measures Learning Appropriate documentation, “hackability” Engagement Ease of discovery, ease of registration Familiarity API styles, message formats and convention Suitability Number of calls required, size of developer stack, latency Aesthetics Appropriate presentation, technology choices Security Pragmatic controls
  28. 28. Who are your Developer Users? Platforms Mobile, web, .net, J2EE Programming Languages iOS, Java, HTML, Node, C++, C# Organization Types Startup, Enterprise, Hobbyist Industry / System Knowledge Expert, Outsider Years of Experience Beginner, Expert
  29. 29. The developer is not always right!  Blindly following users can get designers into trouble  Observe what developers implement rather than just what they say  Organizations must balance developer interests with their own Do it this way!
  30. 30. Security vs. Usability  Security can be a competing concern with usability  The absence of any security may lead to negative feelings (e.g. mistrust, fear)  Implement “just enough” security
  31. 31. Moving Towards a DX Based Design Identify Business Goals Identify Developer Audience Define Interactions Design API
  32. 32. Three Steps Towards a Better DX 1. Write client code 2. Prototype your API 3. Find a developer
  33. 33. Delivering a Developer Experience API
  34. 34. Delivering a Developer Experience Developer Portal
  35. 35. Delivering a Developer Experience API Gateway
  36. 36. Delivering a Developer Experience Developer Portal API Gateway API
  37. 37. Summary  Make rational choices when designing an API  Use a positive DX as your target  Don’t underestimate the importance of usability
  38. 38. Questions? Ronnie Mitra @mitraman Randy Heffner @biztech21