Many of my consulting engagements involve helping teams improve their API products. Over the last decade, I have seen some strategies work better than others. While not every product and circumstance is the same, there are some common mistakes that prevent teams from delivering a great API product. I want to share with you the top five mistakes teams make when it comes to their API product strategy and how you can avoid them.
Mistake #1: Solving the Wrong Problem
Many teams focus on the wrong problem, resulting in delivering an API product that fails to resonate with the target audience. To avoid this mistake, it helps to map out the API and how it fits into the common usage scenarios. This mapping exercise should capture the following:
- The typical pain point that your API solves, e.g. why your API needs to exist
- The overall workflow and how your API fits into it
- The target developer personas that your API targets
- How the API works in cooperation or competitively with other vendors
- How developers will likely discover and subsequently onboard with your API
Mistake #2: Lack of Clarity
Too often, our APIs start off as a series of isolated endpoints that don’t solve a larger problem. This can lead to confusion by developers considering the use of your API, as they may not be sure when and how it fits into their problem.
When first starting out, make sure your API is clear in the problem it is trying to solve, as well as what is isn’t trying to solve. An API that does one thing and does it well through clarity of focus far outweights an API loaded down with lots of disconnected features that doesn’t solve a single problem. Become hyper-focused on understanding the problem and then solving for that specific problem first, before you expand your API’s scope.
Mistake #3: Delivering Features Not Capabilities
Capabilities enable someone to achieve something they previously were not able, such as machine learning or SMS messaging. Features are the individual steps and/or mechanisms that allow them to achieve those outcomes.
As API product owners, we must be able to separate what we are helping our target audience achieve (the capabilities) vs. the features that help them get there (the API endpoints). If you are focused too much on the API design before you know what your audience is trying to achieve, then your API product will fall short. This is often the case for APIs built on top of a database, as the API simply focuses on data delivery rather than desired outcomes of what the API can do for the consumer.
Mistake #4: Lack of Product Ownership
Once your API is delivered into production, your job as API product owner is only getting started. APIs are just like any other product – they must operate on a product lifecycle that matures the product over time.
Most product owners find that there is a whole other world of opportunity that lies beyond the first version of a product. To get to this stage, you must always be focused on the next release. Define your API product roadmap, deliver continuously, and seek input from your stakeholders. Continuous feedback from stakeholders beyond the first release is critical for gaining traction and maturity.
Mistake #5: Long Design and Delivery Cycles
The longer your API takes to get into the hands of consumers, the longer your feedback loop with stakeholders. However, a rushed API often requires changes that will force consumers to adapt or die. How do API product teams balance the need for speed and consumer safety?
I recommend a design-first approach that identifies the capabilities to be delivered, designing the API to meet those capabilities, then delivering the API as fast as possible. To accelerate the delivery process, consider the following:
- Build an API delivery team using cross-functional resources: developers, QA, technical writers, and other roles necessary to deliver the API end-to-end
- Utilize API definition formats, such as the OpenAPI Specification, to communicate the API design to everyone involved
- Take advantage of mocking tools that allow for early experimentation with your OpenAPI definition to work out any design details early, before coding starts (when the cost of API design change is much lower)
- Keep stakeholders involved early and often through shared design documents and mockups
- Deliver the API continuously rather than all-at-once, using stakeholder feedback to prioritize the delivery schedule based on their needs
Remember: Once released, it is difficult to change an API design. Use this accelerated delivery process to expedite your learning and stakeholder feedback early, to avoid needing to make drastic design changes after your API is released.
