What makes a great API? And how do you go about building a successful one? Miguel Carranza, CTO at RevenueCat, shares ten learnings from firsthand experience in architecting an API & SDK that is currently on 5,000+ apps and has seen 3x growth Year-over-Year.
Carranza begins by sharing his high-level thoughts on making a top-tier API: “In my opinion, there are two main things that make a great API. The first one, like any other product, is the user experience. In this case, our users are developers, so I would say that developer experience is the main thing. But even if [developer experience] is great, you still need your API to be reliable.”
Part 1: Developer Experience
- Documentation: Your documentation is important because it’s the first contact you have with your developers. If your documentation looks great, then they might consider implementing your solution, but if not, they will likely move on to another solution.
Strong documentation also helps SEO, improves your funnels, and will help reduce support tickets. But remember, documentation is an ongoing process. Keep a feedback loop open with your support team to deliver the best documentation possible at every stage. - Unexpected Use Cases: Ideally, your API will be designed in a robust way that leaves zero room for error. But at scale, people will use your API in crazy ways that you might not imagine, so some margin of the unexpected is unavoidable. Try your best to prepare for less common scenarios as you are building your API..
- Consistency: Developers are logical people. They dislike inconsistencies, so do your best to avoid these. Carranza recommends managing your API the way you would manage any other product. When you’re building, pay very close attention to detail.
- Depreciation: Sometimes, you might need to deprecate your API, but you must have a very strong, well-thought-out plan in place to do so. You don’t need to live with your mistakes forever, but existing customers should not be penalized. Encourage necessary upgrades, but support the old versions as long as you can.
- Internal vs. External Endpoints: Unified APIs are wonderful, but sometimes splitting them makes more sense. (E.g., sync vs. async operations, SDK vs. Developer API, SDK vs. Dashboard, etc.). Your guiding star should be the customer’s ease of use.
Part 2: Reliability
- On-Call Rotation: Set up your staff schedule as an on-call rotation, and don’t hesitate to implement it, even if you are in the early days of your business. Carranza mentions that they waited a bit too long to set on-call schedules in place at RevenueCat, but fortunately, they gleaned some valuable learnings from the experience. Carranza recommends that you create a fire drill document, conduct your post-mortems in a blame-free manner, automate as much as possible, and ideally aim for five or more people in rotation.
- Simplicity: Keep everything straightforward when building your API –– simple stack, simple architecture, simple infrastructure. Carranza emphasizes, “When you are designing something for scale, people tend to think, ‘Oh, I need to have this super complicated architecture to make sure that we scale.’ But the reality is that when you’re trying to find product-market fit, that probably shouldn’t be your concern.” Instead, the CTO suggests that you avoid adding new pieces of infrastructure until absolutely necessary. Simplicity in an API will make it easier to hire, onboard, gain deep knowledge about the tools, and ultimately, it will be easier to scale.
- Do Not Early Optimize: Wait to optimize because you might not know for sure where the bottleneck actually is. It could cost you lots of effort, and in the end, it might be useless if the real problem isn’t addressed. Always optimize for the most common case.
- Always Be Looking For the Next Bottleneck: Be proactive, monitor, and stay on top of predicting the next bottleneck and single points of failure. Plan and rehearse any migrations.
- Limits: Nothing is entirely infinite, so it’s better to plan and think about it earlier. Consider things like rate limits, field lengths, metadata size, etc. Since it’s challenging to predict, it’s easier to increase than to decrease once you have users.
Key Takeaways
- Treat your API as you would any other product.
- Always put developers first. Make them want to use your API.
- Once developers are using it, consistency and reliability are essential for success.
