Upload
andrew-seward
View
374
Download
0
Embed Size (px)
Citation preview
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