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!