How to Talk about APIs

Andrew Seward

Head of Product at Cronofy

@MrAndrew

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

Accounting

Support

Legal Product Owners

Press Customers

@MrAndrew

Tips for how to talk about APIs

@MrAndrew

BAD OPENING LINES

@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

use Secure Well

documented RESTful

Authentication Endpoints Requests /

Responses Errors

Technical Implementation

De

tail

The 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 providers

connect 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 API

Show word definitions on Kindle

Amazon

@MrAndrew

Establish a ubiquitous language

that 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