The document discusses best practices for APIs and developer experience. It covers the growth of the API economy and importance of APIs for enabling application development. The document then discusses API design principles, different API styles like REST and GraphQL, security practices, and the full lifecycle of building, maintaining and consuming APIs. It emphasizes the importance of consistency, documentation, tooling and processes to ensure high quality APIs.
2. 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
3. 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
5. 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
6. 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:
7. 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
8. 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
9. 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
10. 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
11. 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
12. 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
13. 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
14. 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
15. 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
16. 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
17. 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
18. 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
19. 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
20. 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
21. 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”
22. 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
23. 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
24. 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
25. 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
26. APIS & DEVELOPER EXPERIENCE
REAL WORLD API - GITHUB
26
Request
Response
Resource pluralization
POST to collection
201 Status
Hypermedia URLs
27. 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
28. 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
29. 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
30. 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
31. 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
33. 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
34. 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
36. APIS & DEVELOPER EXPERIENCE
DEVELOPER EXPERIENCE ENGAGEMENT
36
DISCOVER LEARN SUCCEED RETAIN
Understand What
I can Achieve
TTFHW
App
Published
Usage &
Retention
STAGES
GATES
37. 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
38. 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
39. 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
40. APIS & DEVELOPER EXPERIENCE
SUCCESS OBJECTIVE: PUBLISH APP
40
DISCOVER LEARN SUCCEED RETAIN
Easy to Get Support
Friendly Pricing
Great Reference Docs Video Walkthroughs
41. 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
42. 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
43. 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
44. APIS & DEVELOPER EXPERIENCE
NEWSLETTERS & BLOGS
▸ Nordic APIs
▸ API Evangelist
▸ Launchany Newsletter
▸ Net API Notes Newsletter
▸ GraphQL Weekly Newsletter
▸ The API Changelog Newsletter
44
45. APIS & DEVELOPER EXPERIENCE
API PM RESOURCES
‣ Adidas API PO Training
‣ Get in the Van - Michael Sippey
‣ The World Through an API - A16Z
45
47. 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
48. 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