Date post: | 07-May-2015 |
Category: |
Technology |
Upload: | ca-api-management |
View: | 2,195 times |
Download: | 0 times |
Designing Usable APIs
Ronnie Mitra Randy Heffner
@mitraman @biztech21
Questions
-Chat any questions you have and we’ll answer them at the
end of this webinar
- Today’s event hashtag: #L7webinar
Follow us on Twitter:
@layer7 @mitraman
@forrester @biztech21
Webinar Housekeeping
The Keys To Well-Designed APIs
Randy Heffner, Vice President & Principal Analyst
November 6, 2013
Enterprises are deep into APIs
Sample business goals for external APIs
Allow customers to directly manipulate account and
order information
(Saxo Bank, Optify)
Customer service
Create end-to-end monitored process flow across
customers and partners
(Con-Way Freight)
Process optimization
Provide useful data that people can build into
consumer-facing apps
(USA Today, Yellow Pages)
Market mindshare
Build volume by letting others sell your products as their
own
(Travelocity, Expedia)
White-label your business
Let partners seamlessly embed your business into
their offerings
(Amazon store, Sears)
Channel enablement
© 2013 Forrester Research, Inc. Reproduction Prohibited 6
Strong API design: Five major areas
• Based on business context of API use and design API categories
• Function, purpose, architecture context API types
• Messaging style, request structure, payloads, quality of service
Interface technical design
• Effect of API limits, testing, support Community concerns
• Open-ended design, portfolio management
Future preparation
Business context sets API category
Open web APIs
Tech-savvy consumers
B2B APIs
Internal APIs
Product APIs
Value-add innovators
Digital disruptors
Suppliers Distribution
partners
Digital experiences (mobile, web, etc.)
Enterprise applications (custom, off-the-shelf, cloud, on-premise)
Products (software,
physical products, services)
Enterprise customers
Web site developers
Your enterprise Your products
Tech-savvy consumers
Product ecosystem
Wide-open to innovation Optimized business Build product ecosystems
Enterprise customers
1 2
3
4
© 2013 Forrester Research, Inc. Reproduction Prohibited 8
Purpose and function drive API types
• Play in the data economy
• Direct entity/collection access Data APIs
• Complex, multiple resource interactions
• Push processes forward Transaction APIs
• Technical connections between siloed applications Integration APIs
• Serve UI fragments and fully-formed UI components User interface APIs
• Provide business function support Application
component APIs
• Technical support, such as security, logging, and format conversion Utility APIs
Mobile needs multiple API types
Device
UI-level APIs
Core SOA business transactions
UI logic
API façade for core transactions
Mobile backend
Core systems
Local / cached data
UI
Local / cached data User
interface APIs
Data APIs
Trans-action APIs
18%
14%
19%
15%
8%
6%
26%
27%
15%
18%
16%
11%
7%
7%
4%
4%
6%
4%
25%
26%
30%
33%
40%
40%
1%
1%
3%
1%
3%
1%
23%
25%
30%
29%
27%
38%
Service-oriented architecture
APIs exposed internally
SOAP-based services
Message-oriented middleware
APIs exposed externally
RESTful services
Implemented, not expanding Implemented, expanding Planning to implement
No plans Decreasing or removing Don't know/N/A
REST vs SOAP: Watch out for religion
Source: Forrsights Developer Survey, Q1 2013
Which of the following architecture styles does your organization
currently use or plan to use?
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
Net expansion
audience
15%
19%
21%
16%
33%
33%
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
© 2013 Forrester Research, Inc. Reproduction Prohibited 12
Alternate API types fit special contexts
• UI development (Twitter Embedded Timeline) JavaScript APIs
• Natural programming constructs
• Can layer on top of API-based services (Box)
Language bindings (i.e., SDKs)
• Good for periodic info distribution RSS and Atom
• Good for continuous info distribution (E*Trade) Streaming API
• XMPP for bioinformatics
• Ford OpenXC USB, Bluetooth Special cases
REST: Design for comprehensibility
https://api.mycompany.com/name-of-api-request?parameter=abc URI:
domain name encryption URI path query string
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 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
Simple if can be, complex if need be
JSON | XML | XHTML | ZIP | others
no links | links as HTML relations | links as payload data | others
Payload:
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
No links: Simplest for reach to a broad audience
<rel>: Provides for parsing for a specific link type
In-payload: Greater programming flexibility
REST verbs: Not as clear as you think
GET | POST | PUT | DELETE | HEAD | OPTIONS | PATCH HTTP verb:
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
© 2013 Forrester Research, Inc. Reproduction Prohibited 16
REST attachments: No easy way
• Simplest, but must have Internet address
• Separate calls for each attachment URI reference
• Single request
• Larger message size
• Nontrivial for API users and providers
Binary in the payload
• Clarity on media types
• Separate calls for each attachment
• No place for metadata upon retrieval
Separate attachment API
• Single request; best efficiency
• More difficult to program
Multipart messages
One way or the other, plan for versioning
https://api.mycompany.com/v2/name-of-api-request?parameter=abc URI:
Early, for API “family” management
https://api.mycompany.com/name-of-api-request/v2?parameter=abc URI:
https://api.mycompany.com/name-of-api-request?version=2 URI:
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/. . .
Late, for API independence
Query string, to make it optional – Danger Zone
© 2013 Forrester Research, Inc. Reproduction Prohibited 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 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
Ronnie Mitra
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?
?
How do you design an API?
1. Identify resources
2. Design URIs
3. Define operations
bushels
/bushel/apples
GET
apples
/bushel/apples
This is not enough!
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
Negative Feelings
Confusion Mistrust
Isolation Anger
Embarrassment Abandonment
Frustration Neglected
Partner API DX
Positive Feelings
Safety Trust
Empowerment Amazement
Eagerness Pride
Familiarity Inspired
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
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
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
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!
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
Moving Towards a DX Based Design
Identify Business
Goals
Identify Developer
Audience
Define Interactions
Design API
Three Steps Towards a Better DX
1. Write client code
2. Prototype your API
3. Find a developer
API
Delivering a Developer Experience
Developer
Portal
Delivering a Developer Experience
API Gateway
Delivering a Developer Experience
API Gateway
Developer Portal
API
Delivering a Developer Experience
Summary
Make rational choices when designing an API
Use a positive DX as your target
Don’t underestimate the importance of usability