API management solution vendors may need to read up on relationship counseling. They may not be saving marriages, but one aspect of their API management services that vendors need to think about carefully is how well they support and facilitate the relationship between API providers and API users.
However, there is no one answer to the question of what this relationship should ideally look like. Randy Heffner, an analyst for Forrester Research and author of the 2016 Q4 Forrester Wave report on API management solution providers, explained that the picture of an ideal relationship varies depending on the type of API in question, but said that there are three major categories of APIs that can be used to illustrate how this relationship should look: broad, open-web APIs; B2B APIs; and internal APIs. He also explained what vendors can do to ensure a healthy relationship exists between providers and users.
Randy Heffneranalyst, Forrester Research
Open-web APIs, sometimes called public APIs, are open to anyone on the web with minimal vetting, Heffner said, and managing this relationship means serving a broad group of developers. This means that API management solution vendors need to make sure they help providers make APIs easy to access and work with. This includes supporting an API portal that is engaging, organized and helps developers be self-sufficient. This ease-of-use aspect is important regarding open-web API providers because these APIs need to be thought of as a product, Heffner said.
"You're trying to get excitement built around your APIs," Heffner said. "For the open-web developers, the product management type of mindset really takes a stronghold."
Heffner said that when it comes to these open-web APIs, leading management solution providers successfully tie discussion forums to individual APIs, and leverage those forums in a way that promotes the co-creation of APIs and new versions of APIs. He also said that standout vendors provide built-in trouble ticketing with their solutions and provide high levels of portal customization and extension. Finally, he said that having a wide variety of the way API products are specified and priced is a plus.
B2B APIs, also called partner APIs, facilitate a business relationship between two or more organizations. Because of this, Heffner said, this relationship between the API provider and the API user can be thought of as a company-to-company relationship. However, as Heffner pointed out, this type of API relationship should not take individual developers out of consideration because of their role in working with the APIs.
"It may be that the developer actually initiates the relationship between two organizations as B2B partners, or it may be that the partnership exists and the two want to further the efficiency and integration and flow via API-based integration between the two," Heffner said. "So, the API user organization enlists its developers to sign off [on] the portal and use the portal."
Heffner said API management solution providers should also pay attention to the fact that B2B APIs encompass a variety of interactions, such as electronic data interchange, and that all these different types of interactions need to be managed holistically. He also made note of the fact that these APIs can potentially carry a significant value -- to the tune of millions of dollars per API call. This means API management solution providers should carefully ensure, for instance, the B2B API portal is managed reliably and securely.
Heffner also explained even though a B2B API may not be known publically and is designed only for established partners, the portal and ease-of-use aspects associated with open-web APIs should still be considered.
Heffner said top API management solutions typically recognize that the B2B API user is, in fact, an entire organization rather than an individual developer. This involves paying close attention to things like federated identity and controlling access to API keys. And it is not individual developers who are responsible for dictating this kind of governance, he said; it is the responsibility of the organization as a whole to dictate these policies. As such, a leading API management solution provider should recognize this distinctive feature of B2B APIs.
Internal APIs, also known as private APIs, are only used within one company for internal development. An ideal relationship when it comes to internal APIs, Heffner said, requires an established connection between API management and governance inside the enterprise. However, he pointed out that many companies do not always handle this governance aspect very well.
"Many out there these days -- the developers, in particular -- are worried because enterprise architecture teams and others have often not done governance well," he said.
One approach to this governance issue, Heffner said, is to mix architecture governance in with agile development and continuous delivery processes -- something known amongst some as "agile plus architecture." Heffner also cautioned that managing the internal API relationship effectively involves careful construction of an API portfolio and strict identification of responsibilities. This involves identifying and understanding who owns a particular API, what kind of visibility it has, what kind of control certain users are granted and more.
For internal APIs, Heffner said, leading vendors tend to pay close attention to the availability of governance management tools, how easily portals are accessed, how portals are managed, how documentation is handled, how versioning is done, how their management solution can be integrated with DevOps and continuous delivery processes and how much the tool can be built into a toolchain.
Heffner also said lifecycle management is a critical part of providing strong API management solutions, but far too many vendors who claim to provide API lifecycle management do not. Rather, he said, they provide tools that address design, implementation, testing and other parts of the API lifecycle individually, but do not address the lifecycle holistically.
"That's not lifecycle management. What that means is that you're addressing stages in the lifecycle," he said. "That's good, but lifecycle management says, 'How do I get some governance and control over what gets from one stage of the lifecycle to another?'"
Heffner pointed out that across all of these API types, documentation is important. Often developers can find documentation via open API specifications like Swagger, but this is usually minimal documentation. Vendors need to go deeper with their documentation management.
"Often, you need to understand more and a broader context of how you use multiple APIs," Heffner said. "So, documentation, how it's managed … and also how it's tied to specific versions of APIs, that's important."
Management of documentation is the most common kind of improvement vendors could make, Heffner said. This includes creating a closer tie between design tools and documentation. This also includes managing documentation better in concert with versions of APIs.
Management of OAuth 2.0 is another area where vendors could improve. Most vendors provide support for OAuth 2.0, Heffner said, but providing support does not necessarily mean that OAuth 2.0 is implemented into the product in a way that makes sense. This includes ensuring that when customers are presented with an OAuth 2.0 authorization form that specifies which applications or services can be accessed by an API, the text on the form makes it explicitly clear which capabilities will be enabled.
"You can't specify the name of the OAuth 2.0 capability and the scope name in one place and the description in another and tie it in to the API," Heffner said. "Most of [the vendors] need to be more rigorous about how OAuth 2.0 is specified. This doesn't have to do with OAuth 2.0 support. … They can support it, but how is it specified and configured? That is the weakness."
Heffner said that the OAuth 2.0 aspect is important for the vendors of API management solutions to address because the end users may not be thinking about whether it is specified well or not. The users may see that OAuth 2.0 is supported and believe that is good enough; however, there is more to be considered from a business-process standpoint. He gave an example where poorly implemented OAuth 2.0 could allow someone to transfer money out of a bank account when that person was only supposed to be allowed to view the balance of the account.
"These things are possible through business process failures that have nothing to do with how OAuth2.0 is supported or not," Heffner said. "It's like leaving the keys under a rock by the front door."
Find out why API clients aren't optional anymore
Here are five API management products worth taking a look at
How to hammer out your cloud API management strategy