My definition of an API product

What is an API Product ?

An API product is a packaged API solution that offers a benefit to an API consumer. There are 9 important aspects of an API product.

  1. A defined consumer: Who are the likely developers who will integrate with and consume this API and what market are they in ? Creating design personas can help instil a consumer-centric view of the API product. Understanding the industries the developers are in and the solutions they are trying to build is important. All this helps us look at our API not just from the perspective of what it can do, but more importantly what the consumers want to do with it.
  2. The core problem solving benefit the API provides: The value proposition of the API should be clearly defined. What is the core consumer need the product will satisfy? Understand the job the consumer is trying to fulfil and how the API will help fulfil that job.
  3. Business capabilities the API will support: What will be the scope and responsibilities of the API product ? What are the business capabilities it should support ? This will help define the boundary of the API.
  4. The bundled API solution(s): What are the programming interfaces the consumer will be integrating with? For example in a microservices architecture, a public API product may expose programming interfaces that are connected to one or more microservices at the backend. The interface solution the product provides will follow a specified architectural style – for example REST, GraphQL or gRPC. Note that an API solution can be bundled in one or more API products, and an API product can include one or more API solutions.
  5. The usage and pricing plans: For example, how may requests are consumers allowed per day (i.e quota limits) ? Do consumers have read-only access or can they write as well ? Is the API product free to use or is there a price associated with it ?
  6. The security model: What security credentials do the consumers of the API need to provide? Is the API using basic authentication, API keys or token based authorization ?
  7. Documentation and support: There should be an API reference and API guides to show developers how to integrate and consume the API. These are usually provided via a developer portal. As part of that documentation, is the API lifecycle defined with clear guidance on the deprecation and sunset policies ? What stability and performance guarantees are provided ? What is the breaking change policy ? Is there an API product roadmap ?What support channels are available to the consumer if they have an issue using the API ?
  8. Product KPIs: What API product metrics will be used to measure the success of the API product ? For example, is it API usage growth, API monthly active users or API calls per business transaction ?
  9. Assigned API product manger: Who is responsible for understanding the needs of the API consumer, ensuring that the right features are built into the API product, ensuring the API achieves the business goals, and manages the overall development of the API product ?

Where should you define your API product ?

The API product should be defined in an API product profile document that stakeholders in the enterprise can access. This document can be a word document, excel file, or internal wiki page. My preferred solution is to define it in markdown in my APIOps CI/CD pipeline. Here is an example API product profile.

Example: API Product Profile for a Text Messaging API.
No Aspect Product definition
1 API consumers Developers building enterprise applications that send text messages.
2 Core benefit Enables API consumers send and receive text messages.
3 Business capabilities 1) Send messags 2) Receive messages 3) Manage contacts 4) Query metadata information on sent and received messags 5) Create message templates
4 API product manger John Smith
5 API solution REST API. Supported in the backend by Messaging, Contacts, Notification and Template microservices.
6 Usage and pricing plans £0.03 per text message sent.
7 Documentation and support Available at developer.acmemessaging.com
8 API product KPIs 1) Number of sent text messages 2) Monthly active users 3) API usage growth
9 Security model OAuth 2.0
10 Access level Public

Note the extra item I included in the template – the access level. This tells us if the API is public, private or internal, and its useful to capture this on the profile.

After the product profile has been properly defined, discussed and refined with the appropriate stakeholders, as part of the API development process it can be implemented in an API gateway (for example Apigee) by the API development team and described as necessary on the developer portal.

When an API product definition is not documented in an accessible format, there is a risk that it may only be defined in its implementation in the API Gateway . Because the definition of the API product is hidden away in the API gateway, it is difficult for product management to understand and give the necessary attention to shaping the API product.

Conclusion

Thinking about and documenting these 9 points will help you adopt a consumer-centric view on your API offering.


Revision history

2021-12-27: Rewrote the post, expanding the number of API product aspects.

2021-12-30: Added more info to the ‘A defined consumer’ point.

Leave a Reply