Five Universal Principles of API Design
-
Upload
ca-technologies -
Category
Technology
-
view
749 -
download
5
Transcript of Five Universal Principles of API Design
![Page 1: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/1.jpg)
Five Universal Principles of API Design
Ronnie Mitra
DevOps: API Management and Application Development
CA Technologies
Director of API Design
DO3T26T
@mitraman
#CAWorld
![Page 2: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/2.jpg)
[…] there is nothing made by human beings that does not involve a design decision somewhere.Bill
Moggridge
![Page 3: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/3.jpg)
Why do we want better APIs?
Expose More Capabilities
Develop Better Applications Faster
Acquire More Developers & Users
![Page 4: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/4.jpg)
Universal Principles of DesignRockport Publishers Inc.
2007
Authors:
William Lidwell
Kritina Holden
Jill Butler
![Page 5: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/5.jpg)
80/20 Rule
Accessibility
Advance Organizer
Aesthetic-Usability Effect
Affordance
Alignment
Anthropomorphic Form
Archetypes
Area Alignment
Attractiveness Bias
Baby-Face Bias
Biophilia Effect
Cathedral Effect
Chunking
Classical Conditioning
Closure
Cognitive Dissonance
Color
Common Fate
Comparison
Confirmation
Consistency
Constancy
Constraint
Contour Bias
Control
Convergence
Cost-Benefit
Defensible Space
Depth of Processing
Design by Committee
Desire Line
Development Cycle
Entry Point
Errors
Expectation Effect
Exposure Effect
Face-ism Ratio
Factor of Safety
Feedback Loop
Fibonacci Sequence
Figure-Ground Relationship
Fitts’ Law
Five Hat Racks
Flexibility-Usability Tradeoff
Forgiveness
Form Follows Function
Framing
Freeze-Flight-Fight-Forfeit
Garbage In-Garbage Out
Golden Ratio
Good Continuation
Gutenberg Diagram
Hick’s Law
Hierarchy
Hierarchy of Needs
Highlighting
Horror Vacui
Hunter-Nurturer Fixations
Iconic Representation
Immersion
Inattentional Blindness
Interference Effects
Inverted Pyramid
Iteration
Law of Pragnanz
Layering
Legibility
Life Cycle
Mapping
Mental Model
Mimicry
Mnemonic Device
Modularity
Most Advanced Yet-
Acceptable
Most Average Facial-
Appearance Effect
Normal Distribution
Not Invented Here
Nudge
Ockham’s Razor
Operant Conditioning
Orientation Sensitivity
Performance Load
Performance Versus Preference
Personas
Picture Superiority Effect
Priming
Progressive Disclosure
Propositional Density
Prospect-Refuge
Prototyping
Proximity
Readability
Recognition Over Recall
Red Effect
Redundancy
Rosetta Stone
Rule of Thirds
Satisficing
Savanna Preference
Scaling Fallacy
Scarcity
Self-Similarity
Serial Position Effects
Shaping
Signal-to-Noise Ratio
Similarity
Stickiness
Storytelling
Structural Forms
Symmetry
Threat Detection
Three-Dimensional Projection
Top-Down Lighting Bias
Uncanny Valley
Uncertainty Principle
Uniform Connectedness
Veblen Effect
Visibility
Visuospatial Resonance
Von Restorff Effect
Wabi-Sabi
Waist-to-Hip Ratio
Wayfinding
Weakest Link
![Page 6: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/6.jpg)
80/20 Rule
Accessibility
Advance Organizer
Aesthetic-Usability Effect
Affordance
Alignment
Anthropomorphic Form
Archetypes
Area Alignment
Attractiveness Bias
Baby-Face Bias
Biophilia Effect
Cathedral Effect
Chunking
Classical Conditioning
Closure
Cognitive Dissonance
Color
Common Fate
Comparison
Confirmation
Consistency
Constancy
Constraint
Contour Bias
Control
Convergence
Cost-Benefit
Defensible Space
Depth of Processing
Design by Committee
Desire Line
Development Cycle
Entry Point
Errors
Expectation Effect
Exposure Effect
Face-ism Ratio
Factor of Safety
Feedback Loop
Fibonacci Sequence
Figure-Ground Relationship
Fitts’ Law
Five Hat Racks
Form Follows Function
Framing
Freeze-Flight-Fight-Forfeit
Garbage In-Garbage Out
Golden Ratio
Good Continuation
Gutenberg Diagram
Hick’s Law
Hierarchy
Hierarchy of Needs
Highlighting
Horror Vacui
Hunter-Nurturer Fixations
Iconic Representation
Inattentional Blindness
Interference Effects
Inverted Pyramid
Law of Pragnanz
Layering
Legibility
Life Cycle
Mapping
Mental Model
Mimicry
Mnemonic Device
Modularity
Most Advanced Yet
Acceptable
Most Average Facial-
Appearance Effect
Normal Distribution
Not Invented Here
Nudge
Ockham’s Razor
Operant Conditioning
Orientation Sensitivity
Performance Load
Performance Versus Preference
Personas
Picture Superiority Effect
Priming
Progressive Disclosure
Propositional Density
Prospect-Refuge
Prototyping
Proximity
Readability
Recognition Over Recall
Red Effect
Redundancy
Rosetta Stone
Rule of Thirds
Savanna Preference
Scaling Fallacy
Scarcity
Self-Similarity
Serial Position Effects
Shaping
ignal-to-Noise Ratio
Similarity
Stickiness
Storytelling
Structural Forms
Symmetry
Threat Detection
Three-Dimensional Projection
Top-Down Lighting Bias
Uncanny Valley
Uncertainty Principle
Uniform Connectedness
Veblen Effect
Visibility
Visuospatial Resonance
Von Restorff Effect
Wabi-Sabi
Waist-to-Hip Ratio
Wayfinding
Weakest Link
Flexibility-Usability Tradeoff
Forgiveness
Immersion
Satisficing
Iteration
![Page 7: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/7.jpg)
1. Flexibility-Usability Tradeoff
![Page 8: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/8.jpg)
Flexibility
“How many problems will this help me solve?”
“How many ways can I use this?”
“How much stuff can this thing do?”
![Page 9: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/9.jpg)
Usability
“How easily can I accomplish my goals?”
“How difficult is it too get started?”
“What do I need to know?”
![Page 10: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/10.jpg)
adding functionality increases
complexity
Low Complexity
Minimum Capabilities
![Page 11: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/11.jpg)
Maximum Capabilities
adding functionality increases
complexity
High Complexity
![Page 12: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/12.jpg)
added complexity can increase confusion
!!!
Low Complexity
High Complexity
![Page 13: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/13.jpg)
An API designed for applications
GET /account
GET /customer
GET /transfers
POST /transfer
![Page 14: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/14.jpg)
An API designed for an application
dashboard
GET /dashboardMetrics
![Page 15: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/15.jpg)
Flexibility is valuable when we are uncertain
about future user needs
![Page 16: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/16.jpg)
Flexibility is valuable when we are uncertain
about future user needs
Data Chunking
Querying
Order of Calls
Endpoint Location
Data Model
Capabilities
APIClient
![Page 17: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/17.jpg)
UsabilityAid
Flexible System
![Page 18: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/18.jpg)
AndroidJavaSDK
HTTP Based API
![Page 19: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/19.jpg)
This is not a binary tradeoff
Flexibility Usability
![Page 20: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/20.jpg)
Every design decision places you on the spectrum
MaximumFlexibility
MaximumUsability
![Page 21: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/21.jpg)
2. Forgiveness
![Page 22: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/22.jpg)
Forgiveness
Help users recover from mistakes
Help users avoid making mistakes
Warn users of danger ahead
![Page 23: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/23.jpg)
APIClient
Oh Larry…. I forgive you.
`
I’ve made a horrible mistake!
![Page 24: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/24.jpg)
APIClient
Application Developer
Application User
![Page 25: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/25.jpg)
Encourage exploration and learning by providing safe places
Application Developer
Client API
!
![Page 26: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/26.jpg)
Encourage exploration and learning by providing safe places
Application Developer
Client API sandbox
![Page 27: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/27.jpg)
Provide reversibility in the API
Client
Application UserUNDO
![Page 28: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/28.jpg)
UNDO
Provide reversibility in the API
Application User
APIClient POST /undo
![Page 29: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/29.jpg)
3. Immersion
![Page 30: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/30.jpg)
The best moments usually occur when a person’s body or mind is stretched to its limits in a voluntary effort to accomplish something difficult and worthwhile
MihalyCsikszentmihalyi
![Page 31: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/31.jpg)
Application Developer
Client API
![Page 32: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/32.jpg)
![Page 33: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/33.jpg)
4. Iteration
![Page 34: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/34.jpg)
An Iterative API Design Approach
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
![Page 35: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/35.jpg)
Why?
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
revenue reach innovation
growth compliance intel
![Page 36: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/36.jpg)
platform
language
organization
distance
knowledge
risk profile
investment
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
For Whom?
Expertise
Goals
Familiarity
![Page 37: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/37.jpg)
Ideate, Experiment, Sketch & Prototype
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
![Page 38: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/38.jpg)
Test Assumptions
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement Lab Evaluation
Peer Evaluation
User Observation
Write Client Code
Participatory Design
![Page 39: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/39.jpg)
Design Doesn’t Stop
1 Determine Goals
2 Identify Users
3 Design Interface
4 Evaluate
5 Implement
Analyze Real Usage
Identify Usability Bugs
Improve Functionality
Iterate and Evolve
![Page 40: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/40.jpg)
Iterations will improve design
API implementations are difficult to change
Try to iterate before implementation
![Page 41: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/41.jpg)
5. Satisficing
![Page 42: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/42.jpg)
Herbert A. Simon
Searching for the best can only dissipate scarce cognitive resources; the best is the enemy of the good.
“
”
![Page 43: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/43.jpg)
“The best design decision is not always the
optimal design decision.”
Scale
Revenue
Competition
-£ £ £
![Page 44: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/44.jpg)
5. Satisficing
4. Iteration
3. Immersion
2. Forgiveness
1. Flexibility-Usability Tradeoff
![Page 45: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/45.jpg)
80/20 Rule
Accessibility
Advance Organizer
Aesthetic-Usability Effect
Affordance
Alignment
Anthropomorphic Form
Archetypes
Area Alignment
Attractiveness Bias
Baby-Face Bias
Biophilia Effect
Cathedral Effect
Chunking
Classical Conditioning
Closure
Cognitive Dissonance
Color
Common Fate
Comparison
Confirmation
Consistency
Constancy
Constraint
Contour Bias
Control
Convergence
Cost-Benefit
Defensible Space
Depth of Processing
Design by Committee
Desire Line
Development Cycle
Entry Point
Errors
Expectation Effect
Exposure Effect
Face-ism Ratio
Factor of Safety
Feedback Loop
Fibonacci Sequence
Figure-Ground Relationship
Fitts’ Law
Five Hat Racks
Flexibility-Usability Tradeoff
Forgiveness
Form Follows Function
Framing
Freeze-Flight-Fight-Forfeit
Garbage In-Garbage Out
Golden Ratio
Good Continuation
Gutenberg Diagram
Hick’s Law
Hierarchy
Hierarchy of Needs
Highlighting
Horror Vacui
Hunter-Nurturer Fixations
Iconic Representation
Immersion
Inattentional Blindness
Interference Effects
Inverted Pyramid
Iteration
Law of Pragnanz
Layering
Legibility
Life Cycle
Mapping
Mental Model
Mimicry
Mnemonic Device
Modularity
Most Advanced Yet-
Acceptable
Most Average Facial-
Appearance Effect
Normal Distribution
Not Invented Here
Nudge
Ockham’s Razor
Operant Conditioning
Orientation Sensitivity
Performance Load
Performance Versus Preference
Personas
Picture Superiority Effect
Priming
Progressive Disclosure
Propositional Density
Prospect-Refuge
Prototyping
Proximity
Readability
Recognition Over Recall
Red Effect
Redundancy
Rosetta Stone
Rule of Thirds
Satisficing
Savanna Preference
Scaling Fallacy
Scarcity
Self-Similarity
Serial Position Effects
Shaping
Signal-to-Noise Ratio
Similarity
Stickiness
Storytelling
Structural Forms
Symmetry
Threat Detection
Three-Dimensional Projection
Top-Down Lighting Bias
Uncanny Valley
Uncertainty Principle
Uniform Connectedness
Veblen Effect
Visibility
Visuospatial Resonance
Von Restorff Effect
Wabi-Sabi
Waist-to-Hip Ratio
Wayfinding
Weakest Link
![Page 46: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/46.jpg)
46 © 2015 CA. ALL RIGHTS RESERVED.@CAWORLD #CAWORLD
Q & A
![Page 47: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/47.jpg)
47 © 2015 CA. ALL RIGHTS RESERVED.@CAWORLD #CAWORLD
Recommended Sessions
SESSION # TITLE DATE/TIME
DO3T25TTech Talk: Hypermedia-Driven Orchestration
in Microservices11/18/2015 at 2:00 pm
DO3X96S
Tech Primer: Implementing Adaptable
Microservices; A Methodology for Loosely-
Coupled Components
11/18/2015 at 3:00 pm
DO3X95S
Tech Primer: Accelerating the Mobile App
Development Process – How to Simplify
Building Context Aware and Reactive Mobile
Apps
11/18/2015 at 4:30 pm
![Page 48: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/48.jpg)
48 © 2015 CA. ALL RIGHTS RESERVED.@CAWORLD #CAWORLD
Must See Demos
Unlock the Value of APIs
API Developer Portal
Theater 3
Simplify API Design & Creation
Live API Creator
Theater 3
Accelerate Mobile/IoTDevelopment
Mobile App Services
Theater 3
Extend Existing Architectures
API Gateway
Theater 3
![Page 49: Five Universal Principles of API Design](https://reader033.fdocuments.net/reader033/viewer/2022051502/58eea3de1a28abd7718b45b7/html5/thumbnails/49.jpg)
49 © 2015 CA. ALL RIGHTS RESERVED.@CAWORLD #CAWORLD
For More Information
To learn more, please visit:
http://cainc.to/Nv2VOe
CA World ’15