How to Talk about APIs

Andrew SewardHead of Product at Cronofy@MrAndre

w

WE WILL COVER

• Why APIs are hard to talk about• Why this is a problem• Tips for talking about APIs• The importance of establishing an

accessible ubiquitous language

@MrAndrew

APIs are hard to talk about

@MrAndrew

EXERCISE

Describe your API or technical product

@MrAndrew

TECHNICAL PEOPLE THINK OF APIS LIKE

NON-TECHNICAL PEOPLE THINK OF APIS LIKE

Why are APIs hard to explain?

@MrAndrew

DESCRIBE A CHOCOLATE BAR

@MrAndrew

DESCRIBE AN API

?

@MrAndrew

This is a big problem!

@MrAndrew

You need non-technical people

Sales Marketing

AccountingSupport

Legal Product Owners

Press Customers@MrAndrew

Tips for how to talk about APIs

@MrAndrew

BAD OPENING LINES

“Works great

with Node”“It’s an API that…”

“Soooo RESTful…”

@MrAndrew

EXPLAINING YOUR API

Describe the real world impact of

using your product

@MrAndrew

@MrAndrew

EXPLAINING YOUR API

Overview / Elevator Pitch

Use case Use case Use case Use caseIt’s an

APIEasy to

useSecureWell

documented

RESTful

Authentication Endpoints Requests /

Responses Errors

Technical Implementation

Deta

ilThe Product

Differentiating features

Basic features

Instructions

Nobody cares

GIVE A PRODUCT OVERVIEW

…..…. allows …………..… to ………………

<Product> <target customers><business activity>

@MrAndrew

GIVE A PRODUCT OVERVIEW

…..…. allows …………..… to ………..………………

Cronofy software providersconnect to their users’ calendars

@MrAndrew

DESCRIBE KEY FEATURES WITH EXAMPLES

…for example, ……….. uses ………………………..

to ……………………….<API or feature>

<Achieve real-world outcome>

<existing customer>

@MrAndrew

DESCRIBE KEY FEATURES WITH EXAMPLES

…for example, ……….. uses ………………………..

to ……………………….The Oxford University Press Dictionary APIShow word definitions on Kindle

Amazon

@MrAndrew

Establish a ubiquitous languagethat everyone can understand

@MrAndrew

THE LANGUAGE WE USE

• Governs how we think about our APIs

• Establishes the shared understanding within the

organisation

• Keeps all the output of the company consistent with the

product

• Keeps development rooted in real world customers and

use cases

• Makes it easier to work together

@MrAndrew

WE COVERED

• Why APIs are hard to talk about• Why this is a problem• Tips for talking about APIs• The importance of establishing an

accessible ubiquitous language

@MrAndrew