In the first article of this series, I went over the five major capability areas application programming interface (API) management technologies should provide:
- API portal/consumer engagement
- Service lifecycle management
- Integration/service exposure
- Policy enforcement
- Instrumentation, analytics and reporting
In this article, I'll delve into more details on the first two of these, API portal/consumer engagement and service lifecycle management (SLM).
Application programming interface portal/consumer engagement capabilities allow services and their APIs to be discovered by potential consumers, and then manage the required interactions. Service lifecycle management is the other side of the equation. It's focused on the documentation and processes associated with building the service, getting it exposed to potential consumers, and tracking and managing the changes throughout the service's lifecycle and its APIs.
The power of API portals
With more and more public APIs every day, an API portal is a must. In the heyday of SOA, vendors were pushing service registries and repositories. Since the majority of service use was internal, organizations sometimes relied solely on knowing the right people to talk to, or leveraging existing portals for the various IT teams. If services are opened to the public, that won't cut it. A Web-based presence is needed to establish an engagement with the parties interested in using the service.
More on API tools and management
Guide to API trends and best practices
How to make API strategy decisions
Unlocking the business value of APIs
This portal must have a searchable and browsable inventory of available services and their APIs. The search must minimally support keyword searching, but preferably must extend to include metadata-driven search. Metadata-driven searches are likely more appropriate for internal consumers, but they may make sense for external consumers as well.
The portal needs to be supported by a flexible information model for tracking the various attributes of the service and its API. This might include a mapping to a capability model or the major data domains used by the service. At a minimum, it should support keyword-based tagging of services, allowing for ad hoc categorization. This metadata can then be used to establish navigation pathways through the service catalog.
There are two more key consumer-side features an API tool must have. The first is consumer onboarding. This must include:
- A mechanism for a consumer to establish identity keys for use in service invocations,
- Billing and payment information if there will be a fee for usage, and
- Capturing expected or capped utilization.
The second must-have feature to look for in an API tool is a dashboard showing key metrics associated with the invocations by this consumer's registered identities.
The role of an API manager
Service-level management capabilities are focused on the role of the API manager/service owner. This role is best thought of as a product manager, a role that often doesn't exist inside the enterprise. The importance of this role can't be understated, especially if APIs will be exposed to the general public.
An API manager must listen to customers.
An API manager must listen to customers. Therefore, an API management offering must enable customers to provide feedback and must enable API managers to publish news back out to them, including update notifications, retirement of older versions and inquiry responses.
Interaction with the development team is another key role for an API manager. This includes planning future enhancements, resolving problems, defining upgrade paths to new versions, handling compatibility issues with previous versions and ensuring enhancements are delivered on time. While many of the aforementioned things can be handled through normal systems development lifecycle, or SDLC, management tooling, API management tooling needs to complement these tools by providing portfolio-level information about the suite of services and APIs under management, in addition to the information from customers. Systems development lifecycle management tooling will not typically provide insight into which customers will be impacted by a particular change, nor will it publicize backlogged and upcoming releases to customers.
The common piece between API portal/consumer engagement capabilities and SLM capabilities is the flexible information model. It's one thing to have a well-documented service page, but with only a template-driven Web page for each service, reports on which APIs and services are in use by a particular consumer cannot be easily obtained. Reporting the number of different APIs that exist for a particular capability area and planning for consolidation and/or rationalization cannot be furnished.
The final point to consider is that a key aspect of these two capability areas is usability, especially on the API portal side of things. It's hard to take a checklist-based evaluation approach on a user interface, so it's important to spend hands-on time with the evaluated API tool, preferably with role-appropriate testers. An evaluation of API portal capabilities by an API manager may yield results that are very different from the results of an evaluation by an end consumer.
About the author:
Todd Biske is an enterprise architect with a Fortune 50 company in the St. Louis metro area. He has had architecture experience in many different verticals, including healthcare, financial services, publishing and manufacturing, over the course of his 20-year career.