Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

Don't overlook portals, management in the API tool selection process

Application programming interface portals and service lifecycle management are two areas that need to be examined when you consider an API tool.

In the first article of this series, I went over the five major capability areas application programming interface (API) management technologies should provide:

Binary code and blue light
  • 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.

Follow us on Twitter at @SearchSOA and like us on Facebook.

Dig Deeper on Distributed application architecture

Join the conversation


Send me notifications when other members comment.

Please create a username to comment.

Which of the following do you think is most important for API managers?
If you cannot satisfy the customers needs, you have nothing to keep them in a relationship with you.
Right on, Charlie. It's amazing how many organizations seem to have forgotten the importance of basic customer service.