The Path to Success

Ronnie MitraDirector of DesignAPI Academyronnie.mitra@ca.com

May 2015

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

The Path to Success

Ronnie MitraDirector of DesignAPI Academyronnie.mitra@ca.com

May 2015