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

@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 case

It’s an API

Easy to useSecure

Well document

edRESTfu

lAuthenticatio

n 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 ……………………….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