02 api academy - path to success
TRANSCRIPT
What is the API Academy?
Implementing an API is easy.
Implementing an effective API is difficult!
A Simple API Product Lifecycle
Planning
&
Analysis
Design
Implementation
Maintenance
API Lifecycle at Higher Resolution
API Software Life CycleAPI Documentation
Life CycleAPI Tooling Life Cycle
Finding The Path To Success
Finding Your Path
Strong ExecutionGood Design
Why Good API Design Matters
API Program Goals
1. Get more developers using the interface
2. Get applications to market quickly
The Benefits of a Usability and Experience Focus
1. A better experience (increased adoption)
2. Ease of use (shorter dev cycle)
Why Good API Design Matters
The API Interaction: Two Boxes and a Line
APIClient
The API Interaction Revisited
APIClient
development platform
API
Tools
Significant API Product Components
Interface
Learning & Usability Aides
Engagement
Visibility & Analytics
Style and Format(CRUD, SOAP, Hypermedia, Event-Driven, XML, JSON, …)
Navigation & Controls(URI format, queries, hyperlinks, …)
Behaviour(read/write support, synchronicity, error handling, … )
Significant API Product Components
Interface
Learning & Usability Aides
Engagement
Visibility & Analytics
Discovery( SEO, registries, runtime discovery, marketing, … )
Capability Detection( landing pages, marketing, metadata, … )
Onboarding( self-service registration, identity management, SLA, EULA, … )
Significant API Product Components
Interface
Learning & Usability Aides
Engagement
Visibility & Analytics
Documentation( reference, tutorials, examples, books, … )
Tools( SDKs, API Explorers, … )
Community( forums, evangelists, social networks, …)
Significant API Product Components
Interface
Learning & Usability Aides
Engagement
Visibility & Analytics
Communication(alerts,email,…)
Visibility(report generation, error tracing,…)
Challenge: Too Many Design Decisions
Let Empathy Be Your Guide
API
API
Know your Users and Design for Them
• User Centred design improves usability and
Experience
• Define your audience before you design
• Make Empathy a part of your process
Challenge: APIs are Difficult to Change
Public APIs, like
diamonds, are forever.Joshua Bloch
“”
How do we avoid making mistakes?
• We don’t!
• Learn from mistakes: more mistakes is better
• But, make mistakes during design and before
implementation
Iterate early
An API Design Approach
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
Why?
1
2
3
4
5
platform
language
organization
distance
knowledge
risk profile
investment
For Whom?
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
Ideate, Experiment, Sketch & Prototype
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
Test Assumptions
Lab Evaluation
Peer Evaluation
User Observation
Write Client Code
Participatory Design
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
Implementation
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
…
Good DesignStrong Execution
Implementation
API Architecture
APIClient
development platform
API
Tools
Ab
stra
ctio
n L
ayer
API Architecture
APIClient
development platform
API
Tools
Private Resources
( code, data, transactions, message
queues, etc… )
Co
nn
ecto
r
API Architecture
APIClient
development platform
API
Tools
Private Component
The Danger of Exposure
API API
API API API
API
ClientApplication
Important Architectural Qualities
• Availability
• Security
• Performance
• Maintainability
• Testability
• Integrability
Impacting Runtime Qualities
• Availability
• Security
• Performance
Rate limiting
Policy
Enforcement
Caching
QA
System Design
Impacting Non-Runtime Qualities
• Maintainability
• Testability
• Integrability
Application
Design
Holistic Design
Strong ExecutionGood Design &
Why?
1
2
3
4
5
platform
language
organization
distance
knowledge
risk profile
investment
For Whom?
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
Ideate, Experiment, Sketch & Prototype
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
• Start with design-focused
sketches
• Built low-fidelity prototypes
• Increase fidelity and
incorporate actual
implementation concerns
Test Assumptions
Lab Evaluation
Peer Evaluation
User Observation
Write Client Code
Participatory Design
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
• Include implementation
concerns in evaluation
• Ensure that design is
practical
• Articulate the implementation
cost
Implementation
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
…
Analyze Real Usage
Identify Usability Bugs
Improve Functionality
Iterate and Evolve
APIClient
API
Tools
code maintainer
system maintainer
system architecture
tools
processes
software code
Designing for Service Maintainers
Properties of a Holistic Design
1. Designed for organizational value
2. Prioritizes a positive user experience
3. Produces a positive experience with an
effective implementation
A Compass For Your Journey
1. Define Value
2. Embrace Empathy for users and developers
3. Iterate your Design Early
4. Implement Connectors
5. Design Holistically
