handy tools for designing great...
TRANSCRIPT
Handy Tools for Designing Great APIs
Mike Amundsen@mamund
training.amundsen.com
http://g.mamund.com/cambook
"A reusable guide to the technology, business, and politics of doing APIs
at scale within the enterprise."
-- Kin Lane, API Evangelist
Designing Great APIs
● APIs as a Product● Design Thinking● An API Design Method● Virtuous Cycle
APIs as a Product
APIabbreviation1. application programming interface
good APIs make interaction easy
Design Thinking
Design Thinking
A design discipline to match people’s needs with what is technologically
feasible and what a viable business strategy can convert into customer
value and market opportunity.
-- Tim Brown, CEO of IDEO
Design Thinking
A design discipline to match people’s needs with what is technologically
feasible and what a viable business strategy can convert into customer
value and market opportunity.
-- Tim Brown, CEO of IDEO
Design Thinking
A design discipline to match people’s needs with what is technologically feasible and what a viable business
strategy can convert into customer value and market opportunity.
-- Tim Brown, CEO of IDEO
Design Thinking
A design discipline to match people’s needs with what is technologically
feasible and what a viable business strategy can convert into customer
value and market opportunity.
-- Tim Brown, CEO of IDEO
Design Thinking
A design discipline to match people’s needs with what is technologically
feasible and what a viable business strategy can convert into customer
value and market opportunity.
-- Tim Brown, CEO of IDEO
Design Thinking
A design discipline to match people’s needs with what is technologically
feasible and what a viable business strategy can convert into customer
value and market opportunity.
-- Tim Brown, CEO of IDEO
Three Elements of Design
Few people think about it or are aware of it. But there is nothing made by human beings that does not involve a design decision somewhere.
“”
Bill MoggridgeInteraction Design Pioneer
FunctionalityUsabilityExperience
design
http://www.flickr.com/photos/monicamuller/3171329060
toast
Functionality
http://www.flickr.com/photos/traviswiens/3761198872/
Usability
Experience
Three Elements of Design
● Functionality● Usability● Experience
An API Design Method
API Design Method
● API Workflow● API Diagram● API Vocabulary● API Profile● API Reference
Produce a Workflow Sketch
Workflow Sketch: Weather API
Draw a Diagram
Diagram: Weather API
WSD format documents
Diagram: Weather API
Bonus Utility -- wsdgen
● CLI app to generate images from WSD format docs
wsdgen weatherAPI.wsd
Apply Vocabularies
Weather Data
● Gather all the property names● Gather all the action names● Normalize vocabularies
○ Open○ Industry○ Internal
Before Applying Vocabularies
Sources for Vocabularies
▪IANA Link Relation Values▪schema.org, Activity Streams▪microformats, Dublin Core▪Industry Vocabularies (Semantic Sensor Web)▪Internal Vocabularies
After Applying Vocabularies
After Applying Vocabularies
Normalize Properties & Specify Actions
Create a Description Document
Description vs. Definitions
▪ Describing the interface doesn't define it.▪ Description languages
▪ ALPS▪ DCAP▪ JSON Home
▪ Definition languages▪ WSDL▪ Swagger▪ RAML▪ Blueprint
Description vs. Definitions
▪ Describing the interface doesn't define it.▪ Description languages
▪ ALPS▪ DCAP▪ JSON Home
▪ Definition languages▪ WSDL▪ Swagger▪ RAML▪ Blueprint
Bonus Utility -- wsd2alps
● CLI app to generate ALPS doc from WSD doc
wsd2alps weatherAPI.wsd weather-alps.json
Generate reference API documentation
API Reference Documentation
● Simple reference docs are handy● But insufficient● Many aspects to human documentation
○ Concepts○ Getting Started○ Common Tasks○ Solving Problems○ Detailed Reference
Bonus Utility -- alps2doc
● CLI app to generate reference doc from ALPS doc
alps2doc weatherAPI.wsd weatherAPI.md
Design Artifacts
▪Workflow Sketch (doc)▪Diagram (wsdgen)▪Description Document (wsd2alps)▪Generate Reference Doc (alps2doc)
Check these into source control
And So...
APIs as Products
Design Thinking
API Design Method
Virtuous Cycle of Design
Available Online...
● Slides (amundsen.com/talks)● Utilities (github.com/api-tool-kit)● Newsletter (g.mamund.com/newsletter)● Books (amazon.com/Michael-Amundsen)
Handy Tools for Designing Great APIs
Mike Amundsen@mamund
Thanks!