Maximizing Product Potential with API-based Customization

Prabath Ariyarathna

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. 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.

Why is customizing API-based product challenging ?

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.

Ways to minimize API modifications/versions?

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.

Here are some key points to minimize API customization.

• Train your customer-facing personnel in basic API knowledge.
• As a solution provider, it's your responsibility to educate client organizations without API experience on basic principles, otherwise future discussions may become difficult.
• Involve technical personnel from the customer side in API discussions to simplify the process.
• Avoid focusing on specific APIs in the solutioning process as it limits flexibility. Consider all APIs in a domain, including supporting domains, as a single product (e.g. booking domain-related APIs). View existing APIs as building blocks for your solution.
  

  Ex:- Customer Request: The customer requires the ability to modify an existing booking created through other interfaces.

  Available APIs:-

  1. The GET /bookings API displays a list of all available bookings, with the ability to filter results. Note that for performance reasons, each booking record contains only a subset of information.
  2. The GET /bookings/{id} API returns detailed information for a specific booking.
  3. PUT bookings/{id} — update specific bookings.
     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.

• Monolithic APIs

  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.
  

Before proposing to enhance existing APIs, consider the following factors.

• Is this the appropriate context (e.g. booking, pricing, etc.) for use?

  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.

• Is this the correct API to enhance?

  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.

  1. GET /bookings - This API retrieves a list of booking details based on specified filters.
  2. GET /bookings/{id} -This API retrieves details for a specific booking.
     The above APIs serve different purposes. When enhancing APIs, it's important to consider actual business requirements, as this may impact non-functional aspects such as performance or security. Adding information that takes time to retrieve or calculate to the booking list API may negatively affect performance, but this information can be included in the booking details API, as it only deals with a single booking

• Experience API layer.
  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

How to maintain the process effectively?

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. The diagram above illustrates the high-level process for external API integration.

1. 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.
2. 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.
3. 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

Prabath Ariyarathna

Prabath Ariyarathna is the Co-founder and Chief Product Officer at X-venture.