The document discusses the benefits of an API-first development approach, emphasizing team collaboration through well-defined APIs that mirror business domains. It outlines principles for designing APIs as consumer-driven products, focusing on user experience, continuous feedback, and iteration to enhance developer onboarding and interactions. The importance of maintaining externalizability, effective documentation, and agile processes is highlighted to ensure APIs meet consumer needs.

1. Dependency Down, Flexibility Up
The benefits of API-first development
Ankit Sobti
Co-Founder & CTO, Postman
PRESENTED BY
May 10, 2019

2. May 10, 2019
About Me
Founder of
Postman
A Builder
Since 2012
Passionate
about APIs
API

3. Postman
API Development Environment
API Workflow
Design & Mock
Design in Postman & use
Postman’s mock service
Debug
Test APIs, examine responses,
add tests and scripts
Automated Testing
Test APIs, examine responses,
add tests and scripts
Document
Create beautiful web-viewable
documentation
Monitor
Create automated tests to monitor
APIs for uptime, responsiveness &
correctness
Publish
Onboard developers to your API
faster with Postman collections
and documentation
Team Library
Collaboration
TeamLibrary
Collaboration
Monitor
Publish
Document
Design & Mock
Debug
Automated Testing

4. May 10, 2019
Bezos Mandate
1. All teams will henceforth expose their data and functionality through service interfaces.
2. Teams must communicate with each other through these interfaces.
3. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of
another team's data store, no shared-memory model, no back-doors whatsoever. The only communication
allowed is via service interface calls over the network.
4. It doesn't matter what technology they use. HTTP, Corba, Pubsub, custom protocols -- doesn't matter.
5. All service interfaces, without exception, must be designed from the ground up to be “externalizable”. That is to
say, the team must plan and design to be able to expose the interface to developers in the outside world. No
exceptions.
6. Anyone who doesn't do this will be fired.

5. May 10, 2019
In other words…
• APIs are the only way to get things done
• Teams collaborate through APIs
• “APIs must be externalizable”
• Key constraint - how APIs are designed, built, and managed

6. May 10, 2019
1. Teams modeled around Business Domain
• Teams are created to follow the business domain within the organization
• Teams display isomorphism with Technical Architecture - Inverse Conway’s Maneuver
• Identifying these service boundaries leads to:
• better team alignment and
• more stable service boundaries,
• avoiding expensive cross-service changes
• Teams become experts in business domains than in specific technologies

7. May 10, 2019
2. Teams collaborate
through APIs
• Context boundaries are explicit
• Domain teams only interface with other domains
through clearly defined APIs
• Important to preserve conceptual integrity of context
• Consumer Driven APIs - not a 1:1 reflection of the
domain model
• Sets up a Dependency Chain between different systems

8. 3. API as a Product
(AaaP)
• Think of APIs as Consumer-Driven Products
• Consumer Research, Design, Prototyping,
Testing, Monitoring, Maintenance
• Applies to Public, Private and Partner APIs - aligns
with “externalization”
• 3 layers:
• Design
• Onboarding
• DX

9. May 10, 2019
Design
• Jobs To be Done - Clayton Christensen
• Why are you building this API?
• What problems are you solving and
how do you prioritize them?
• Who are you solving this problem for?
• Mission Statement for Domain Teams

10. May 10, 2019
Design
• API Interface Model - describes the behavior
of an API from a consumer perspective
• Includes details about communication
protocol, messages, vocabularies
• Acts as a tool for Collaboration - feedback,
review
• Can be expressed using API Description
Formats:
• HTTP - OpenAPI, SOAP - WADL, gRPC -
Protocol Buffers
• Ecosystem advantage - tooling

11. May 10, 2019
• API Design precedes Code
• Explicit process - how heavily to invest time &
resources is a strategic decision
• An Example:
• Create a prototype for the interface - Open
API Spec, Postman Collection
• Share the prototype with the target
consumers - (mock servers)
• Collect feedback, make and validate
changes - (consumer driven contracts)
• Iterate as necessary
Design

12. Onboarding
• Design the experiences that takes a
consumer to:
• learn that the API will solve their
problem(s)
• understand how to use the API
• Time to Get Things Working
• Typically includes:
• Getting started and other initial tutorials
• Analytics of usage of these tutorials

13. API Documentation
• Tool to Teach and Learn about the API
• Ways to Deliver:
• Reference Guide
• highly factual
• better suited for experienced users
• can be generated from API Description
Languages
• Design a Learning Experience
• examples, tutorials, sample applications
• suited for new users, reduce time to get
things working
• Important to keep it in sync with implementation
and instance changes

14. May 10, 2019
Developer Experience
• User Experience for Developers
• acknowledges a continuing, long-term
relationship
• continuous small improvements by
studying consumer behavior and evolving
needs
• measure of how happy your consumers
are
• How are your APIs being used/not used
• Interface Design, Discovery, Documentation,
Support, Marketing - all contribute to DX

15. May 10, 2019
Developer Experience
• Things to Design for:
• Consistency
• Ease & Safety of Use
• Error Reporting & Failure States
• Monitor Usage

16. May 10, 2019
Tools to stay agile in an
API-First World

17. May 10, 2019
Postman Collection
• Executable Description of an API
• Can be linked to Specifications
• Auto-generated documentation
• Collaboratively editable in Workspaces
• Collections can be run anywhere:
locally, commandline, CI or cloud

18. May 10, 2019
1a. Schema
• Understand the why, what, who
• Create a draft of the API in
a description language of your
team’s choice - e.g. OpenAPI
• Share and validate with potential
consumers

19. May 10, 2019
1b. Documentation
• Use tooling to automatically generate
Reference documentation from API
Description Languages
• Publish internally/externally and make
available to all consumers

20. May 10, 2019
2a. Blueprint Collection
• Declaration of “this is how you can and
should use my API” under different
scenarios
• Littered with examples, tutorials, sample
applications
• Outline scenarios, not just requests and
responses
• Also available as auto-generated
documentation

21. May 10, 2019
2b. Mock Servers
• Created directly from the blueprint
collection or the API Description
• Useful for consumers to prototype API
Design during the validation phase
before the provider service is up

22. May 10, 2019
2c. Run in Postman
• Embeddable anywhere on the web
• Make developers instantly actionable
with your APIs - pass signed in context
• Embed examples and scenarios

23. May 10, 2019
3. Consumer Driven
Contracts
• Written by the consumer(s)
• Collections with tests in requests that
assert on the expected response
• Can be built on the API Description,
blueprint collection and the mock server
• Throwaway contracts - tool to codify
“consumer expectations”

24. May 10, 2019
API Versioning
• Sometimes you’ve to break contracts. How do you do that without impacting consumers?
• API Versioning
• Co-existing endpoints and co-existing services
• Should be clearly communicated to the consumers

25. May 10, 2019
Summary
• API First means more than just APIs before code
• Start with clearly defined domain boundaries aligned
along business objectives
• AaaP approach encourages teams to apply Product
and Design thinking to APIs - understand your
consumers and their problems, design iteratively and
constantly seek and incorporate feedback
• Design great onboarding and developer experiences to
make consumers instantly and consistently actionable
• SaaS tools formalize processes into products. Use
them.

26. Thank You!