Deliver a Great Developer Experience (DX) as Part of an Effective API Strategy
Overview
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.
Neo4j - How KGs are shaping the future of Generative AI at AWS Summit London ...
Designing Usable APIs featuring Forrester Research, Inc.
1. Designing Usable APIs
Ronnie Mitra
@mitraman
rmitra@layer7tech.com
Randy Heffner
@biztech21
rheffner@forrester.com
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. The Keys To Well-Designed APIs
Randy Heffner, Vice President & Principal Analyst
November 6, 2013
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)
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. 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. 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
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: https://api.mycompany.com/name-of-api-request?parameter=abc
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. 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. 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
17. One way or the other, plan for versioning
URI: https://api.mycompany.com/v2/name-of-api-request?parameter=abc
Early, for API “family” management
URI: https://api.mycompany.com/name-of-api-request/v2?parameter=abc
Late, for API independence
URI: https://api.mycompany.com/name-of-api-request?version=2
Query string, to make it optional – Danger Zone
Gotta have a good reason:
In the domain name: https://apiV1.mycompany.com/. . .
As a custom media type: application/x-customerV1
In the request payload: {
“version": “v1", . . . }
As an HTTP port number: https://api.mycompany.com:49152/. . .
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. 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. 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
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. 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. 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. 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. 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. Moving Towards a DX Based Design
Identify Business
Goals
Identify Developer
Audience
Define Interactions
Design API
32. Three Steps Towards a Better DX
1. Write client code
2. Prototype your API
3. Find a developer