EMMANUEL PARASKAKIS
API BEST PRACTICES
1

APIS & DEVELOPER EXPERIENCE
THE API ECONOMY
▸ Entire companies have emerged
that just offer APIs as their product
▸ APIs as Product market worth
$6.27B, growing 40%
▸ APIs were 83% of global web
traf
fi
c in 2018
▸ API Management Tools will hit
$5.1B in 2023, at a 33% CAGR
2
Bessemer Venture Partners, State of the Cloud 2020

APIS & DEVELOPER EXPERIENCE
WHAT’S AN API AND WHY IS IT IMPORTANT?
▸ Programmatic Interface to a set of
functionality or data
▸ Application development becomes
easier, faster by consuming building
blocks
▸ You no longer have to be an expert
in a domain to get value from it
(e.g payments, phone/SMS, email,
authentication, shipping, AI)
3
The World Through an API, Martin Casado, a16z

APIS & DEVELOPER EXPERIENCE
API EXAMPLE
4
Request
Response

APIS & DEVELOPER EXPERIENCE
WHAT’S DRIVING THE API ECONOMY
1. Started with app to app integrations, for
data exchange & automation
2. Development of lightweight, easy to use
APIs → wide adoption
3. Expanded with mobile apps that need to
sync or fetch data
4. Skyrocketing due to demand for platforms
and developer ecosystems
5. Emerging Digital Transformation of
incumbent organizations
5
The State of API 2020 Report, SmartBear

APIS & DEVELOPER EXPERIENCE
DIGITAL TRANSFORMATION
▸ Radical rethinking of an existing business by
leveraging technology, people & processes
▸ Enables new business models, new partnerships or a
coordinated response to market and regulatory needs
▸ APIs are a catalyst, used to break down data silos and
surface information that was previously locked up in
legacy data stores
▸ Precipitated by users expecting a customer
experience on par with modern consumer mobile
apps
▸ Makes it easy to surface many, customized
experiences, e.g. web, mobile, kiosks etc.
6
3 Companies doing it right:

APIS & DEVELOPER EXPERIENCE
THE AUDIENCE FOR APIS
▸ Internal APIs: used only inside an
organization - the vast majority
▸ Partner APIs: used by selected
partners, by invitation
▸ Ecosystem APIs: used by anyone
outside the organization
(tip of the iceberg)
7
2020 State of the API Report, Postman

APIS & DEVELOPER EXPERIENCE
HOW WE BUILT APIS & SERVICES
8
API as a by-product
of building apps
API documentation
generated from code
Design-
fi
rst API
Development
API Development
Consistency

APIS & DEVELOPER EXPERIENCE
2006: API AS A BY-PRODUCT
API as a by-product
of building apps
API documentation
generated from code
Design-
fi
rst API
Development
API Development
Consistency
9

APIS & DEVELOPER EXPERIENCE
2010: API DOCS FROM CODE
10
API as a by-product
of building apps
API documentation
generated from code
Design-
fi
rst API
Development
API Development
Consistency

APIS & DEVELOPER EXPERIENCE
API DEFINITION DOCUMENTS
▸ Domain-Speci
fi
c Languages that can be
used to describe an API’s behavior
▸ Human readable/writable and machine-
readable
▸ Once you have an API de
fi
nition, you can
use tooling to render documentation or
even generate tests and clients
▸ Examples: Swagger → OpenAPI, RAML,
AsyncAPI, Proto3, API Blueprint
11
API De
fi
nition
Document
API
Documentation
API Tests

APIS & DEVELOPER EXPERIENCE
OPENAPI
▸ Evolved from Swagger
speci
fi
cation
▸ Most widely used API
De
fi
nition Format
▸ Under Linux Foundation:
OpenAPI Initiative
▸ 3.1 is the latest version
12

APIS & DEVELOPER EXPERIENCE
OPENAPI INITIATIVE
▸ OpenAPI is becoming so much more than
just a Spec: it’s the place where thinking
and collaboration around APIs happens,
whether it’s about the original OpenAPI
description format, or adjacent specs such
as JSON Schema and AsyncAPI, and
beyond.
▸ We think OAI is becoming a focal point
where the requirements of API builders
and API consumers are converging!
13

APIS & DEVELOPER EXPERIENCE
2014: DESIGN-FIRST API DEVELOPMENT
14
API as a by-product
of building apps
API documentation
generated from code
Design-
fi
rst API
Development
API Development
Consistency

APIS & DEVELOPER EXPERIENCE
API DESIGN
▸ We’ve known what makes a good API since Joshua Bloch’s
How to Design a Good API and Why it Matters
1. Easy to learn
2. Easy to use, even without documentation
3. Hard to misuse
4. Easy to read and maintain code that uses it
5. Suf
fi
ciently powerful to satisfy requirements
6. Easy to extend
7. Appropriate to audience
▸ API Design brings intent into the process by authoring an API
De
fi
nition Document, created from scratch and not generated
from existing code - like a wireframe for UI
15
API De
fi
nition
Document
- User Needs
- Vocabulary
- Data Structures
- Validations
- Resources
- Actions
- Error Cases
- Styles & Standards

APIS & DEVELOPER EXPERIENCE
API AS A PRODUCT
▸ As APIs became more important, the industry
realized we need to treat them as products
▸ Emergence of the API Product Manager,
designing an API Product such that it meets
the needs of Developers and their
customers’ use cases
▸ Iterate and get feedback from future API
Consumers
▸ API De
fi
nition Document becomes “contract”
once agreed
16
API De
fi
nition
Document
{ }
Mock
Prototype
Feedback
API
Documentation
API Tests

APIS & DEVELOPER EXPERIENCE
WHY API-FIRST?
▸ API-First means designing the API before any other
layers of you application, such as the UI
▸ Jeff Bezos famously mandated all teams to use service
interfaces which are designed to be externalizable
▸ Start with the API and combine endpoints into different
user experiences, as needs of the market evolve
▸ A great place to start when you don’t know where you’ll
end up but it might mean you risk delivering an API
developers won’t use
▸ May lead to creating numerous versions of the API that
you’ll have to support
17

APIS & DEVELOPER EXPERIENCE
2018: CONSISTENCY ACROSS APIS
18
API as a by-product
of building apps
API documentation
generated from code
Design-
fi
rst API
Development
API Development
Consistency

APIS & DEVELOPER EXPERIENCE
API GOVERNANCE
▸ It’s easy to keep things consistent in a small team that
works on few APIs
▸ Once APIs proliferate across a large organization with
multiple teams, inconsistencies creep in
▸ An inconsistent API is hard to learn and understand
and dif
fi
cult to maintain
▸ Organizations develop API Style Guides and Security
Guidelines, but it’s dif
fi
cult to enforce them without
tooling and processes
▸ A robust API publishing process is needed to
maintain quality, security and control
19
Screenshot from Stoplight Spectral, showing warnings when scanning
an API De
fi
nition

APIS & DEVELOPER EXPERIENCE
API SECURITY
▸ Use common security best practices
as you would with any application
▸ Keep in mind the OWASP API Top-10
▸ Authenticate via proven standards:
Basic Auth, OAuth 2.0 and use HTTPS
▸ Don't leak information in errors or IDs
▸ Protect behind an API Gateway and
Rate limit!
▸ Monitor your services
20
A Design-First Approach for API Security, Keynote at API Days San Francisco, 2018

APIS & DEVELOPER EXPERIENCE
A TAXONOMY OF API STYLES
▸ Web APIs: Generally REST-ish APIs are by far
the most commonly used
▸ Query APIs: GraphQL, when querying is
important but use cases are not known
▸ Publish-Subscribe APIs: Kafka for event-
driven, streaming APIs
▸ RPC APIs: SOAP (don’t), gRPC for ef
fi
ciency,
internal-only apps
▸ Flat File Transfer: Large, batch-type operations
21
For a detailed discussion on which styles to use and when,
see Z’s excellent presentation “What API, Your Guide to API
Styles”

APIS & DEVELOPER EXPERIENCE
RISE OF REST
▸ Most of the APIs used today are
HTTP/JSON “RESTful” APIs
▸ Fully REST-compliant APIs are
rare in the wild and should
satisfy 6 architectural
constraints.
▸ Easy to consume, with existing
tooling, lots of familiarity
because they are web APIs
22
Common API Search terms, Google Trends

APIS & DEVELOPER EXPERIENCE
REST API MATURITY
▸ Level 0: “Plain Old XML”, RPC-style
APIs
▸ Level 1: Use Resources (nouns), not a
single endpoint
▸ Level 2: Use different HTTP methods
(verbs) such as GET or POST
[Aim for at least this level]
▸ Level 3: “Hypertext As The Engine Of
Application State”, linked elements
[Precondition for true REST]
23
Leonard Richardson’s API Maturity Model

APIS & DEVELOPER EXPERIENCE
COMMON LEVEL 2 CONVENTIONS
▸ Use plural for resources,
e.g. /orders not /order
▸ A resource without an ID
represents a collection,
e.g. /customers vs
/customers/123
▸ Resources can be nested to
denote relationship, e.g.
customers/123/orders (but
don’t overdo it)
24
▸ GET to retrieve data, no request body. May
return a single object or a collection
▸ POST to create a new item, send
representation in request body. Response will
contain the created item representation
▸ PUT to modify an item, send the new
representation in the request body. Response
contains the modi
fi
ed representation
▸ DELETE to remove an item, no request or
response body
▸ 200 OK
▸ 201 Created
▸ 202 Accepted
▸ 204 No Content
▸ 400 Bad Request
▸ 401 Unauthorized
▸ 403 Forbidden
▸ 404 Not Found
Naming Resources Method Usage Status Codes

APIS & DEVELOPER EXPERIENCE
EXAMPLE OF AN EVOLVABLE REST API
▸ Use of link relations allows
consuming application to
discover resources
▸ Allows underlying object to
change (authors, categories)
▸ Easy to maintain and modify
25
RESTful JSON design pattern makes it easy to add links in
JSON payloads

APIS & DEVELOPER EXPERIENCE
REAL WORLD API - GITHUB
26
Request
Response
Resource pluralization
POST to collection
201 Status
Hypermedia URLs

APIS & DEVELOPER EXPERIENCE
GRAPHQL
▸ HTTP API with type safety and
querying built-in
▸ Great when the use cases are not
known upfront, i.e. random querying
patterns
▸ JavaScript on frontend
▸ GraphQL schema
▸ Wide adoption: Facebook, GitHub,
Intuit, Audi, Shopify, Atlassian…
27
GraphQL.org

APIS & DEVELOPER EXPERIENCE
EVENT-DRIVEN APIS
▸ Trigger is an Event, not
request/response
▸ Publish/Subscribe
▸ Streaming Data
▸ AsyncAPI is the description
format (based on OpenAPI) -
adoption at Adidas, Salesforce,
Slack, SAP
28
Protocol support:
- AMQP
- HTTP
- JMS
- Kafka
- MQTT
- STOMP
- WebSocket

APIS & DEVELOPER EXPERIENCE
THE API LIFECYCLE - HOW TO BUILD AND MAINTAIN APIS
▸ Ideation: Collect requirements,
data model, vocabulary, goals
[Product Manager]
▸ Design: Iterate on de
fi
nition with
API Consumers via Mock
[Architect/Product Manager]
▸ Development: Implement design
against contract and functional
requirements
[Developer]
▸ Con
fi
guration: Prepare and set up
for deployment
[Developer]
29
Domain Data
Style Guide & Vocabulary
API Description Document
Collections & Scenarios
Runtime Configuration
Developer Portal
API Gateway
Environment
Sandbox
API Consumer

APIS & DEVELOPER EXPERIENCE
RUNTIME ENVIRONMENT
▸ Deployment: Deploy Service via CI/
CD to correct environment, run tests
[DevOps]
▸ Publishing: Make API available on
Gateway and Dev Portal
[DevOps]
▸ Operation: Monitor health and
ensure uptime/security
[DevOps]
▸ Analyze: Review metrics and user
feedback - iterate to Ideation phase
[Product Manager]
30
Domain Data
Style Guide & Vocabulary
API Description Document
Collections & Scenarios
Runtime Configuration
Developer Portal
API Gateway
Environment
Sandbox
API Consumer

APIS & DEVELOPER EXPERIENCE
API CONSUMPTION
▸ Developer Portal: Where API Consumers
authenticate, discover and learn the API
[DevRel]
▸ API Gateway: Authenticates, protects
and meters API calls sent by API
Consumer
[DevOps]
▸ Deployment Environments: Production,
Regional or Test - service API Calls sent
by API Consumer
[DevOps]
▸ Sandbox: Simpli
fi
ed environment where
API Consumer can play with API
[DevOps]
31
Domain Data
Style Guide & Vocabulary
API Description Document
Collections & Scenarios
Runtime Configuration
Developer Portal
API Gateway
Environment
Sandbox
API Consumer

32
API
Description
API
Standards
Data
Models
Security
Standards
Repository
Implementation
Developer Portal
Pricing Catalog Docs Analytics
Runtime
Environment
Gateway
Identity
API Consumer
Dev Rel
Tech Writer
Developer
PM
Architect
CI/CD
& Test
CI/CD
CI/CD
& Test

APIS & DEVELOPER EXPERIENCE
VERSIONING
▸ Possibly the touchiest subject in APIs :)
▸ The consensus is to try to prolong and
avoid it as much as possible but doing
good market research, making your API
evolvable and introducing only non-
breaking changes
▸ Eventually you’ll have to make breaking
changes and then you’ll have to evaluate
different ways to indicate API versions
33
If you MUST version:
URL /api/v2/…
Changes all the
resources
Header Stripe-Version: 2017-05-25 Not Intuitive
Content Type Accept: mymediatype.v2+json Not Intuitive
API Versioning: a case of picking your poison

APIS & DEVELOPER EXPERIENCE
THE API PLATFORM TEAM
▸ Also known as “API Strategy Team” or “API Council”
▸ Responsible for API Standards, Tools and Processes
▸ Approves API Designs and Publishes Services
▸ Can become a bottleneck so try to decentralize approvals
and give teams the know-how and automation to serve
themselves
▸ Exec sponsorship is key to success
▸ Team members: API Architects, SMEs, DevRel
34

APIS & DEVELOPER EXPERIENCE
FEDERATED PLATFORM TEAM
35

APIS & DEVELOPER EXPERIENCE
DEVELOPER EXPERIENCE ENGAGEMENT
36
DISCOVER LEARN SUCCEED RETAIN
Understand What
I can Achieve
TTFHW
App
Published
Usage &
Retention
STAGES
GATES

APIS & DEVELOPER EXPERIENCE
YOUR OBJECTIVE AS A SAAS API PROVIDER
▸ A user must pass through all the gates & all the stages of the funnel
▸ Has an app whose usage is continuously increasing
▸ High Retention, Low Churn, NRR, measure with tools like Moesif
37
DISCOVER LEARN SUCCEED RETAIN

APIS & DEVELOPER EXPERIENCE
DISCOVERY OBJECTIVE: SIGN UP
38
DISCOVER LEARN SUCCEED RETAIN
Content, Messaging, SEO
DevRel
Landing Page per Use Case & Persona
Check out Adam DuVander’s book:
Developer Marketing Does Not Exist

APIS & DEVELOPER EXPERIENCE
LEARNING OBJECTIVE: SHORT TTFHW
39
DISCOVER LEARN SUCCEED RETAIN
Make it Easy to Make that 1st API Call (1-2-3)
Tutorials, Sample Code, SDKs
(but keep them fresh)
Interactive “Try It”
Easy to Get Credentials
Use Playgrounds like
Postman or CodeSandbox

APIS & DEVELOPER EXPERIENCE
SUCCESS OBJECTIVE: PUBLISH APP
40
DISCOVER LEARN SUCCEED RETAIN
Easy to Get Support
Friendly Pricing
Great Reference Docs Video Walkthroughs

APIS & DEVELOPER EXPERIENCE
RETENTION OBJECTIVE: NRR
41
DISCOVER LEARN SUCCEED RETAIN
Build Community
Customer Success
Status &
Dashboard
Keep it Secure
Evolve Sanely
Check Out Orbit

APIS & DEVELOPER EXPERIENCE
WHAT DOES A GREAT DEVELOPER EXPERIENCE LOOK LIKE AND WHY IT MATTERS
▸ Combine a great, consistent API design, with one that
is reliably available
▸ Be careful about versioning APIs; plan ahead and
don’t make breaking changes
▸ Easy to start: Time To First Hello World in a Sandbox
(Authentication is always tricky)
▸ Have a great Developer Portal where it’s easy to
fi
nd:
- Quickstart Guide
- Interactive Reference Documentation
- Tutorials
- Code Examples
- SDKs
▸ Provide easy ways to give feedback and get support
▸ All this means that Developers are likely to try your API
and will create apps that use it
42
Stripe has one of the best API Developer Portals, really makes it easy to
fi
nd information and ticks all the boxes
Navigation Pane
Example Response
Textual Description

APIS & DEVELOPER EXPERIENCE
API MONETIZATION
▸ Most APIs are monetized indirectly: they are Product-led and support the main
product by providing integrations which tend to be persistent or by enabling
lucrative partnerships (e.g. GitHub)
▸ Ecosystem APIs enable developers to build apps that reinforce a platform or
marketplace, also indirect monetization (e.g. Atlassian)
▸ Steady rise of APIs as a Product (See slide on API Economy)
▸ Transactional & tiered pricing (Twilio)
▸ Fixed pricing (SendGrid)
43

APIS & DEVELOPER EXPERIENCE
NEWSLETTERS & BLOGS
▸ Nordic APIs
▸ API Evangelist
▸ Launchany Newsletter
▸ Net API Notes Newsletter
▸ GraphQL Weekly Newsletter
▸ The API Changelog Newsletter
44

APIS & DEVELOPER EXPERIENCE
API PM RESOURCES
‣ Adidas API PO Training
‣ Get in the Van - Michael Sippey
‣ The World Through an API - A16Z
45

APIS & DEVELOPER EXPERIENCE
BOOKS
46

APIS & DEVELOPER EXPERIENCE
TOOLS TO CHECK OUT
▸ API Design
▸ Apiary
▸ SwaggerHub
▸ Stoplight
▸ API Documentation
▸ Readme
▸ Redocly
▸ Optic
▸ RapidAPI
▸ API Testing
▸ Postman
▸ Dredd
▸ API Fortress
▸ Schemathesis
▸ API Management
▸ Apigee
▸ Kong & Insomnia
▸ Solo
▸ AWS API Gateway
▸ API Analytics
▸ Moesif
▸ APIMetrics
▸ Akita
▸ GraphQL
▸ Apollo
▸ Prisma
▸ Hasura
▸ GraphiQL
▸ Security/Availability
▸ 42 Crunch
▸ Salt
▸ APISecurity
▸ APIExpert
47

TEXT
GREAT API EXAMPLES
▸ Adidas API for overall Developer Experience:
▸ Nylas API for breadth of functionality
▸ Stripe for the API Reference, tutorials and sample apps
▸ Twilio for the general documentation format
▸ GitHub for the excellent intros
▸ Dropbox for the API Explorer but not much else
▸ Spotify for overall organization and navigation
48