The Xapi Community is a vibrant network of Xapi Platform users from around the globe: collaborating, innovating, and advancing together towards a more robust API design and governance ecosystem.
Copyright © 2026 X-Venture. All Rights Reserved.
Prabath Ariyarathna
29 April 2023
|13 min read
he key difference between a project and a product is how the vision and requirements are driven. A project is solely driven by the customer's requirements, as it is designed and built for them. Meanwhile, a product team has a roadmap that guides the development, considering factors like industry trends, future predictions, and customer requirements. Customizing the product for specific customers can be a challenge for product teams, especially in industries like airlines where each big customer has unique business processes. The key difference between a project and a product is how the vision and requirements are driven. A project is solely driven by the customer's requirements, as it is designed and built for them. Meanwhile, a product team has a roadmap that guides the development, considering factors like industry trends, future predictions, and customer requirements. Customizing the product for specific customers can be a challenge for product teams, especially in industries like airlines where each big customer has unique business processes.
These modifications can be achieved through the use of design techniques for standalone software, but they are more challenging in API-based applications due to various reasons.
Digital transformation continues to dominate boardroom discussions as businesses increasingly realize the organizational and cost efficiencies that digitization can provide. For many, application programming interfaces (APIs) are an essential component of merging the old and the new IT platforms, capturing vast amounts of data, and ultimately achieving their digital transformation strategy.
An API is an agreement between two parties, and if the agreement changes, external consumers must update their client applications accordingly. This can be challenging in real-world scenarios where various tasks, such as discussions and testing, are involved. API versioning minimizes this impact. If API publishers need to change the agreement(only for breakable changes), a new version is introduced with the changes, while the existing API version remains available for existing consumers. However, this creates additional challenges such as increased support costs from maintaining multiple APIs, especially in multi-tenant platforms with thousands of APIs. The solution is to minimize API versioning and changes.
Product companies aim to provide maximum functional flexibility to their customers to boost sales. This is achieved in standalone applications through configuration options or routing logic. However, product managers aim to reduce customization to prioritize their product vision. If a company holds a significant market share, they have the bargaining power to suggest industry-standard business processes as solution providers. As previously discussed, customizing APIs can be difficult. This can be addressed to some extent if the customer requests customization for an application developed by the same product company. However, if there is a large number of new requirements from external integrations, especially as more companies adopt cloud platforms like Salesforce as a central enterprise dashboard, achieving the same level of flexibility with APIs can be challenging if the client organization and their representatives are not well-versed in API integrations.
Available APIs:-
If a customer lacks technical knowledge, they may request a single API for updates and model their application UI accordingly. However, as the solution provider, it's important to explain the benefits of using a step-by-step process instead of direct updates, including both functional and non-functional benefits.
The above scenario is simple, but there are many other opportunities to effectively propose these ideas.
Every business domain has core sub-domains, which include core business processes. For example, in the airline domain, booking is a core sub-domain. Customers may have varying requirements for these core processes (APIs), as they are crucial to their business. To meet these requirements, different properties may need to be added to the API request and response or change structure, leading to a monolithic API with hundreds of properties and decreased API flexibility.
A monolithic API with hundreds of properties can be difficult to use for simple operations, as it may require filling out fields that are irrelevant.
Ex:- If you're familiar with domain-driven design, you may know about the concept of bounded context. Similar APIs may be exposed from different contexts, each with a unique purpose. Therefore, it's important to identify the appropriate context.
Multiple APIs may exist for the same purpose. The correct API to enhance should be chosen based on both functional and non-functional requirements.
Ex:- The following two APIs are available for retrieving booking details.
The experience API layer is a solution for enriching or personalizing interactions between distributes application or services components. The key to the API experience model is placing a new mediation or abstraction layer between API consumers (apps, external systems) and API provides (digital platform, applications). This layer wraps the backend API and expose personalized and managed APIs.
The API gateway capabilities can be utilized to achieve API experiences related to business context. This approach should be used cautiously to avoid creating hundreds of experience APIs for different customer requirements. As a first step, attempt to negotiate and utilize the existing contract as much as possible and only resort to experiencing APIs as a last option. A balance between customer experience and internal maintainability challenges should be struck.
Ex: Multiple backend systems may offer shipment tracking APIs. Customers may request a single, consolidated tracking API for ease of use. This is a valid request from the API consumer's perspective
Managing a large business platform undergoing digital transformation requires establishing proper processes. APIs are a crucial component and an external interface of the system. Multiple teams may work simultaneously to create APIs, making it essential to establish clear API guidelines. These guidelines should include naming conventions, specifications (e.g. HAL for REST), API versioning, deprecation strategy, documentation, error handling, security, etc. Consistency is key, so all teams should follow the same standards. Large enterprises should establish an API governance team to enforce and preserve standards.
A team comprising domain and technical experts with API knowledge should engage the customer to comprehend their business needs. At this stage, discussions about APIs should be avoided. The primary objective should be to gather the business requirements and assist the customer in refining optimal business solutions. The following points are crucial:
Assist customers in comprehending their actual requirements. When a customer lacks knowledge about APIs, they may ask for what they believe to be correct, but it is our responsibility to educate them on how the API operates and guide them in adjusting their systems to accommodate API-driven designs. Ex: The customer needs to integrate the booking update feature with your APIs. They may initially request booking update APIs for integration purposes, but as API experts, you should clarify that retrieving booking details must occur prior to the update, and additional master data APIs may also be required for successful integration.
Create a flow chart for your business operations. It provides a comprehensive view of your business needs and helps facilitate discussions with the API governance team.
Once the high-level business requirements are confirmed, the team can consult with the API governance team for API solutions. The API governance team, composed of domain and technical experts, offers a comprehensive understanding of APIs, vision, and business. They provide a high-level solution that considers current APIs and requests from other teams. Further discussions with the customer may be necessary to refine requirements. Upon completion, the requirement documents can be signed off and technical details added.
Finalize the API specification for changes or new APIs before development begins. The development team and domain expert for the requirement can collaborate to create the initial specification using standards like OpenAPI Specification v2/3. Obtain approval from the API governance team, which is responsible for validating the specification from both technical and business perspectives.
Share Article
API Design
In today's rapidly evolving digital landscape, organizations are constantly striving to accelerate development, enhance their offerings, and maintain a competitive edge. A critical, yet often overlooked, aspect of achieving these goals lies in the ability to truly see and understand digital assets.
Prabath Ariyarathna
13 February 2026
Read More
API Design
We're thrilled to unveil our latest Xapi platform update, bringing a more intuitive API design experience, tooling enhancements, and a smarter way to govern externally designed APIs. These new capabilities make API design and governance more accessible, more powerful, and more flexible than ever before.
Shamali Sathindra
8 April 2025
Read More
API Design
Every organization wants well-designed APIs, but the key is turning business needs into carefully crafted APIs that perfectly match their main business objectives.
Prabath Ariyarathna
17 February 2025
Read More
