The document provides tips for building API products, including mistakes to avoid. It emphasizes the importance of understanding target developers, giving careful consideration to naming conventions, allowing sufficient time for discovery, design and development, focusing on the entire API ecosystem experience, designing the API organization structure thoughtfully based on Conway's Law, and providing an end-to-end integration experience. The document uses examples and outlines processes to illustrate its recommendations for building APIs.
5. ! Know thy developers
21 years from Ukraine, recent
college grad, Python/Ruby expert,
freelancer $15-25/hr
35 years, Senior
Payments lead, crypto
currency expert,
domain expertise
25 years, Senior engineer high
growth startup (no payments
experience).
9. ! Being obsessive about naming
https://community.babycenter.com/post/a58084684/for_those_of_you_wanting_a_unique_name_for_baby..._meme_included
10. Is it trending, Is it common?
Does the first and last name rhyme?
Is it obvious from the name if the child is a boy or a girl?
Audience: Indians, Americans
Is it similar to someone else’s name in the family?
! Being obsessive about naming
Probability of getting teased?
Any alternate meanings or pronunciations?
11. Inconsistent ( “id”, “identifier”, “xxx_id”)
Doesn’t do what it says (e.g. invoice_number = “INV-1234”)
Probability of misspelling (e.g. preferred_source)
Field in a database (e.g. fname , lname)
Arcane names, understood by developers with domain expertise (e.g. “pan”)
! Being obsessive about naming
Unecessarily abridged names (e.g. acct_no vs account_number)
British/American English (e.g. “colour” or “color”)
Redundant (e.g. gross_total_amount vs gross_amount)
13. ! Time & Due Diligence
DISCOVERY
Problem
Competitors
Customer research
Persona
Business Case
Epics
14. ! Time & Due Diligence
DISCOVERY
Problem
Competitors
Customer research
Persona
Business Case
Epics
DESIGN
End Points, Fields
Security
Mocks
Frontend tools
Specification
User Stories
15. ! Time & Due Diligence
DISCOVERY
Problem
Competitors
Customer research
Persona
Business Case
Epics
DESIGN
End Points, Fields
Security
Mocks
Frontend tools
Specification
User Stories
DEVELOP
Prioritized backlog
Spec to Code
Documentation
SDK
Automated Tests
MVP
16. ! Time & Due Diligence
DEPLOY & LAUNCH
Sandbox availability
User testing
Training
GTM activities
Setup Monitoring
Limited Release
DISCOVERY
Problem
Competitors
Customer research
Persona
Business Case
Epics
DESIGN
End Points, Fields
Security
Mocks
Frontend tools
Specification
User Stories
DEVELOP
Prioritized backlog
Spec to Code
Documentation
SDK
Automated Tests
MVP
18. ! Focus across API ecosystem
SDK (Client, Server, Native)
Developer docs - self serve
Samples / Get Started
Debugging Tools
Training (Sales, Professional Services)
Community / Dev support
Sandbox (on par with production)
…
19. ! Design API Organization
Conway’s law
Any organization that designs a system will produce a design whose
structure is a copy of the organization’s communication structure.
20. ! Design API Organization
API 1
Director of
Product Line 1
API CONSUMERS
API 2 API 3
API Governance
Product
Manager
Engineering
Manager
Director of
Product Line 2
Product
Manager
Engineering
Manager
Director of
Product Line 3
Product
Manager
Engineering
Manager
21. ! Design API Organization
API TEAM / DevX Team
Director of
Product Line 1
API CONSUMERS
Product
Manager
Engineering
Manager
Director of
Product Line 2
Product
Manager
Engineering
Manager
Director of
Product Line 3
Product
Manager
Engineering
Manager
API / DevX Team
Be intentional about how you build an organization knowing it will be reflected in the work (API’s) that is produced.
22. Know thy developers
Being obsessive about naming
Time & due diligence
Design API Organization
Focus across API ecosystem
E2E Integration experience