In an increasingly uncertain year, it’s crucial to keep API ownership costs under control. This article will explore five common mistakes made by API teams that can impact these costs.
While you can prevent some mistakes during the early stages of API design, you can mitigate others after release. By taking a proactive approach, we can effectively manage API ownership costs.
Let’s dive into the details and learn how to avoid these mistakes.
1. Failing to align with developer needs
Too often, developers need help focusing on the internal details of their solution: the code, the data model, and the software components that make up their API. Details such as JSON structures, URL paths, and HTTP response codes become the focus of the conversation.
The end user and API consumers’ needs often need to be remembered, and developers need first fully to align their understanding with the requirements of their consumers.
Aligning what your API needs to do before you complete the coding effort helps put the focus back on the humans that will be using the API. This approach is often referred to as “outside-in API design”.
This means ensuring that we understand the problems they face, the outcomes it helps to produce, and what operations the API will need to provide along the journey. It requires breaking down our assumptions to ensure that every line of code we write delivers on the promise of solving their problem.
Job Stories
Job stories were created by Alan Klement and are based on Jobs-to-be-done ( JTBD) formulated by Clayton Christensen. They offer a simple framework to capture all of the aspects of the job to be done.
Job stories offer an easy way to capture these early details and the jobs to be done for any product, including the customer motivations, events and expectations for a new product, service, or API.
They frame every design problem from the perspective of the customer. Job stories seek to identify the issues that customers have and the eventual outcome they wish to achieve. You identify jobs that will solve these problems, and APIs will offer digital capabilities to power these jobs to produce the desired result.
Key takeaway
Become hyper-focused on understanding the problem and then solving that specific problem first. Use job stories to capture and share insights. This will prevent future rework, avoid throwing away code, and reduce your support costs.
2. Selecting the wrong API style
There are many choices of API styles, from REST and GraphQL to RPC and beyond. Too often, teams select their preferred API style based on what is new and shiny or what will get them their next job opportunity. Once the consumers start to use your API, they may encounter challenges due to unfamiliarity with the chosen API style.
This will increase the cost of support as you help them get started. At the same time, this may seem like a small cost; multiply this by the number of API consumers using your API, and it adds up quickly.
Select the API style that meets the needs of your API consumers rather than the one that caters to the technical interests of the API provider team. This may require interviewing your target audience to understand their needs, including their preferred API style.
Just because you like REST and JSON or GraphQL doesn’t mean they will.
While you wait to gather these details, spend some time modelling your API. This API model represents the high-level details about what the API will need to support, including:
- The operations that your API needs to provide
- A name for the API
- The scope of its responsibilities
- Input/output details, including resources that your API will manage.
Once you know the API style, map the API model into that specific API style.
The Align-Define-Design-Refine (ADDR) process is a lightweight approach that incorporates these API design steps into an approachable, repeatable API design process.
The process groups the step-by-step process into four distinct phases: Align, Define, Design, and Refine. It works with an agile software development process and helps to mitigate API design risks early.
Key takeaway
Select the API style that matches the needs and familiarity of your API consumers. Selecting the wrong API style will result in an API not being used or requiring considerable cost and effort to support and maintain later.
3. Treating APIs as technology, not products
Organisations that treat APIs as purely a technology solution may incur a high cost of ownership for their API. They will fail to engage with their target audience to understand their needs. Over time, it requires considerable effort to adapt the API to different needs, incurring a high cost of development time. It’s better to address new demands than throw away code and start over.
Some teams delivering APIs often assume that the first release of the API will be the only release necessary, other than the occasional bug fix. That could not be further from the truth. Like any web or mobile application, APIs require continuous improvement. Once your API is in production, your job is just getting started.
APIs are like any other product — they must operate on a product lifecycle that matures the product over time. Most product owners find that there is an opportunity beyond the first release of an API product.
You must always focus on the next release to engage with this product mindset. Seek input from your stakeholders, define an API product roadmap, and deliver continuously. Continuous feedback from stakeholders beyond the first release is critical for gaining traction and maturity.
Key takeaway
You should treat an API like a product, not a bolt-on technology solution to an existing product. Continuously seek feedback from existing and future customers. Maintain a separate API product roadmap, and deliver improvements through subsequent releases.
4. Releasing frequent breaking versions
When you create a new major version of an API, you start the sales process again with your API consumers. Change the code to adapt to your breaking changes and retest existing integrations. Your API re-design becomes the consumer’s problem.
API providers can mitigate customer churn by maintaining multiple major versions in production. However, there is no guarantee that your consumers will switch to the latest version.
Instead, they will force you to maintain multiple API versions in production indefinitely. They may even choose to switch API providers completely, resulting in increased customer churn.
Instead, try and find ways to minimise the need for releasing major versions by introducing non-breaking changes to your API. Non-breaking changes are additives, such as adding new response fields or operations. In this case, you are simply releasing a new API revision that will not negatively impact the consumer.
Key takeaway
Every new major API version released is like a new product requiring additional infrastructure, support, customer relationship management, and development costs to maintain.
Keep this in mind when the temptation arises to release a new API version to fix that annoying design decision that crept in last year. Instead, find ways to introduce improvements without breaking existing API consumers.
5. Missing sales opportunities due to poor documentation
API documentation is the most critical user interface for developers consuming your API. It is the primary communication channel between the API provider and the many developers who will consume the API.
Most API teams assume that reference documentation for each operation is sufficient; however, that is only the beginning of the API documentation effort.
Additional things to consider for your documentation include the following:
- Spend time refining your API overview to quickly address benefits, capabilities, and pricing to qualify prospects and save your sales team spending time on unqualified leads.
- Use various case studies to highlight applications built using the API to help convert prospects into customers.
- Offer a getting started or quick start guide to help developers get started quickly, reducing the support costs of new customers.
- Ensure authentication and authorisation processes are transparent so you can complete the initial onboarding of new customers without considerable time and effort from your support staff.
- Provide release notes and a changelog that includes new operations and enhancements to existing processes to help existing customers take advantage of new capabilities quickly. This will reduce customer churn as they continue to see the additional value your API provides.
Key takeaway
Documentation not only helps developers succeed quickly, but it also helps to keep down the cost of supporting your API and reduces customer churn. It can also act as a first-line sales engineer to accelerate prospects through the sales process.
Keeping API ownership costs under control
To control the ownership costs of an API, API teams need to avoid critical mistakes that can increase the cost of supporting and maintaining your APIs. These mistakes can occur during the API design phase or at any other point in the API lifecycle.
Here, we identified five such errors. By reviewing these mistakes and applying the recommended solutions, API teams can reduce their overall cost of API ownership, regardless of the phase they are in.
We encourage API teams to carefully consider these recommendations and take action to avoid these mistakes.
