Post on 22-May-2020
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