Designing & Developing Productized APIs

APIs undergo various stages in their lifecycle as they are created, used, and eventually retired. Different definitions of the API Lifecycle define these stages differently, but generally, they correspond to four high-level stages: design, development, deployment, and distribution. These stages are applicable to API implementations regardless of internal or external deployment.

Given the increasing focus on external API implementations, particularly in operationalizing machine learning, HLS, and financial services data, certain considerations should be made at each stage. We’ve seen that APIs aimed at external users also present a new set of concerns – ranging from protection from reputational damage to managing the demands of a wildly successful monetization initiative – that require product management expertise not required for APIs tailored for internal use.

In light of our experience productizing APIs, we'd like to share some reflections on how they inform the larger stages of the API lifecycle.

Design

The design stage of the API lifecycle is the initial phase, where the developers plan and create the API. During this stage, developers traditionally determine the purpose and functionality of the API, including what data it will provide, what actions it will perform, and how it will interact with other software systems.

Here are some examples of how product-level API decisions can impact an API design and should be considered earlier in the Productized API lifecycle:

• Product Definition: APIs are often grouped together as products in API Marketplaces and API Management Platforms. These groupings are usually defined by API Product Managers to serve a specific use case or target market. For example, we sometimes see a “Retail Banking Package” packaged separately from a “Commercial Banking Package.” Due to the differences between these two groups' needs, the APIs may be designed differently from the outset, and without sharing this strategy with the development team, the API implementation will drift away from business requirements. Developers should know which larger group (or groups) they will belong to when designing APIs. It may affect how API verbs and resources are structured as well as how they are documented.
• Pricing Model: For directly monetized APIs, the Product Definition must include the target pricing model in the design phase as this has many flow-down effects discussed in the points below. To help with examples we have observed, imagine your business team envisions building pricing tiers based on the high-water mark in transactions per second for each customer, or they desire to charge customers a higher unit cost for queries against one set of data and lower unit costs for a separate dataset. If these requirements are not known to the development team from the beginning, products will require a large amount of developing rework and generate frustration on all sides.
• Consumption Tracking (Metering): As previewed in the pricing model discussion, determine upfront how API usage will be licensed and how this will impact API implementation. For example, if the confidence interval of a machine learning model’s prediction impacts the cost of an API, persisting and exposing this metric should be taken into account sooner rather than later. If you make your pricing model clear from the beginning, developers will understand the importance of communicating the confidence interval to the rating engine and how this impacts API pricing.
• Service Level Availability Targets: API developers need to understand the reliability level they aim for with an API’s implementation, particularly if they intend to offer different reliability commitments for your API at different price points. This will affect the implementation plan, the architecture, and the reporting requirements for the API. These requirements will generally come from the business and external customers of a Productized API. The biggest risk to development efficiency in this area is not understanding the reliability commitments from the business during the design phase, as changes to architecture toward the end of a development lifecycle are extremely expensive. Lastly, even if your business teams do not intend to offer a SLA at this time, you should track these operational metrics regardless because they will provide you with a good understanding of API consumer experience. Moreover, in the future if/when you are asked to implement a service level guarantee, you will have empirical data to show your ability to meet the desired targets before they are promised to customers.
• Quota Measurement & Enforcement: Productized APIs that are monetized will often have a quota associated with various tiers of usage segmented by price. Developers implementing the API need to understand what the usage metrics encompass, which metrics most impact price, and how quotas will affect access to the API. For example, developers need to know if the application is expected to block access to users when they exceed their quota or simply notify the business that it has occurred, or, perhaps if they’re lucky, whether they can simply offload this requirement to a turnkey API Monetization Platform. 😀

Development

API implementation occurs during the development phase of the API Lifecycle. This phase includes several activities that are essential to create an effective and functional API. An API's development phase is crucial to ensuring that it is reliable, secure, and functional.

Because productized APIs are intended to be exposed externally, they require additional development in several key areas.

Security: Productized APIs must be properly secured against threats due to their external nature. This is particularly acute as Productized APIs almost always have value attached to them, which may or may not be directly monetized but are still critical to the business. APIs also may need to be restricted to certain organizations or users. For example, highly specialized HLS or financial services APIs may only be exposed to consumers from a particular geography or email domain vs. the general public. A request to a Productized API request may also contain details about the contractual arrangement of the consumer, so that API implementations can tailor the API response according to a licensing entitlement or association with an organization. Billing: Productized APIs must be capable of charging consumers for their usage in order to be monetized. From a development perspective, ensure that you have accounted for the following: - The ability to correlate an API credential from your API gateway to a customer (company) and an end user (developer) - The ability to consolidate API usage across multiple users (and generally multiple credentials) from the same company into a single invoice. If you are offering volume-based discounts, ensure that the combination of usage from multiple users is appropriately discounted based on total usage from all users in a single company. - The ability to correlate a company who uses your API to a record in your CRM & ERP so that usage and costs related to an API user once invoiced are tracked appropriately in the company ERP. - The ability to correlate revenue from a given product or API and track it to the appropriate profit center in your ERP. - The ability to offer refunds for various reasons - The ability to generate and send invoicing PDFs automatically at the end of every billing period - The ability to invoice & collect payments via credit card automatically for smaller customers who prefer to pay this way - The ability to automatically disable accounts with past-due invoices (most important in high-volume, self-service API sales models), and to re-enable them automatically once payment is made.

We hope that this summary of how Productized APIs impact the first two API lifecycle stages is helpful to you as you plan your own API product roadmap. In a future post, we will explain the key changes that productized APIs require in the final stages of the API Lifecycle, Deployment, and Distribution.