Which Combination of API Strategies Do You Need to Win?
Should you be API-First AND Design-First? Let’s explore what works and what doesn’t, depending on your business model.
I’ve interviewed thousands of API teams while working on API Design, Documentation, and Testing tools as a VP of Product Management for Apiary and Smartbear, and I’ve seen what works and what doesn’t.
✅ Design-First and API-First: Great for large, global organizations with thousands of Internal services. E.g. Google Cloud, AWS, OCI, Azure.
✅ Design-First and API-Product: For companies planning to sell transactional APIs with usage-based billing - think Twilio or Stripe, as an example.
✅ Design-First, API-First and API-Product: Organizations that have Internal, Partner, and Public APIs and need maximum efficiency across all three - Banks, Telcos, or Global Retailers, for example.
⚠️ Code-First: Totally OK if you are a small team and don’t plan for other teams or third parties to use your APIs. Perhapapps.
⚠️ API-Product: Pair with technical talent. Hire an API Architect/CTO to ensure you have a sound technical foundation. Then bring in a Design-First mentality to make sure you are building the right product.
⚠️ API-First and API-Product: You need a way to validate your API in the market and after that, a way to evolve sanely going forward. So invest in API Product Management and a Design-First approach before you go too far.
⚠️ Code-First and API-Product: Unless your team is extremely disciplined, you run the risk of making breaking or undocumented changes in customer-facing APIs. This will create a bad experience and will cause low adoption and churn.
❌ API-First and Code-First: Without artifacts that help your teams understand the intent of your services, you’ll end up in an inconsistent state. Introduce a source of truth for API designs and automated tooling to ensure you’re following them.
And finally:
❌ API-First, Code-First, and API Product: You’ll be pushing a rock up hill for larger organizations. Too many things happening at the same time.
Last but not least, please pick either Design-First or Code-First. DO NOT mix the two where you have a design doc and then make decisions in code, then autogenerate the design doc, and then overwrite the original one. This is a recipe for chaos in any but the smallest teams.
There’s no one-size-fits-all approach, and there will always be someone who has made even “bad” strategies work for their own unique situation. But if you want to be directionally correct and not make it hard on yourself and your team, follow the guidelines in the attached PDF.
I’d love to hear your opinion about your experience with API Strategies in the comments on the original LinkedIn post. And please reach out to me with a DM if you need help choosing a strategy.