To many, it may not come to a surprise that API management platforms are a great way to further API development...
and management with minimal overhead. The opinionated architecture of these platforms leads to reduced overhead and shared knowledge within engineering teams, and their user-friendly nature empowers nontechnical staff to make meaningful changes to documentation, provide support and review analytics.
- Should you go with an on-premises or cloud platform?
- How big is the support infrastructure?
- What documentation method is available?
- Is it going to cost a fortune?
One of the most important questions to ask when weighing the pros and cons of API management software is this: Why is one unified platform better than multiple, targeted tools?
If your organization already has an established API, it's entirely possible that you have a piecemeal solution in place for API management. Documentation, testing, security and scalability are all big areas where individual tools exist. While using multiple API tools might feel like less of a commitment, they can often leave something to be desired. These tools may lack in how they integrate with each other, and how accessible they are to employees outside of the engineering team.
So, when ultimately considering the purchase of an API management platform, what features should you actually consider? While this might seem like a pretty loaded question, the answer isn't nearly as complicated as you'd think. At a high level, there are really only a few major areas to consider when making your choice: user support, usability and implementation.
As with any new technology, evaluating how its users are supported is crucial. There's no use committing to a platform that has a history of poor support. One of the biggest challenges with in-house solutions is a lack of third-party support. When something goes wrong, it is up to the engineering team to fix it. This can have drastic consequences on developer productivity.
That said, there are two different ways in which an API management platform is likely to be supported: internally or externally.
Internal support typically comes in the form of both self-serve support, like documentation and FAQ pages, and managed support, such as a help desk. Like most commercial software offerings, you'll tend to find that the more advanced internal support is costlier. It's important to note here that the way your API management software is sold is a good indicator into how the support is managed.
A direct sales-driven process tends to lend itself to more direct communication with the vendor, which means that you can expect a more personalized support process (a direct contact or phone support), while an organic sales process often comes with an asynchronous support queue like email.
External support, on the other hand, tends to refer to a more crowdsourced approach, such as message boards, social media and real-time chat communities. While many solutions with great internal support also have community support, open source providers and lower-cost options tend to have a very vibrant community of developers. The reason for this is due to the increased accessibility of the platform for smaller organizations with fewer resources.
Proprietary answers to internal problems don't often lend themselves to a high level of usability. There are a lot of reasons for this, but the one that I've experienced most often is time. When launching a product, more often than not, the priority lands on the customer-facing side.
Administrative tools are either afterthoughts or they contain the bare minimum of functionality and design. One of the biggest advantages to using an API management platform is usability. While each platform will have its own unique feature set, there are a few areas of usability that are important to be aware of:
Metrics. Plugging an analytics platform into a product often requires some developer intervention, such as adding tracking code or integrating a metrics API directly in the software, but it is important to understand how people are using your product. On the flip side, when someone is abusing the system, engineers often rely on the logs over a third-party option. API management platforms that provide metrics and monitoring can help reduce this strain by providing an easy-to-use interface for keeping track of how an API is being used at any given time.
Documentation. There are quite a lot of stand-alone project documentation tools available, but one of the biggest advantages to the documentation tools provided by an API management platform is the ease of use. Many open source documentation tools require some developer intervention, whether through updating markdown files or interacting with a version control system. But API management platforms that provide documentation tend to take a no-code approach to it. This can give nontechnical staff an opportunity to easily update documentation language and structure, as well as speed up documentation writing within the development team.
Design. Often going hand-in-hand with documentation, many API management platforms provide API design functionality as well. As a developer, one of the most frustrating things that can happen with an API is finding out-of-date documentation. API management platforms that verify the documentation against the design ensure that the documentation is always up to date with the actual API specifications.
Additionally, platforms that provide a front-end interface for designing an API specification can give your team the ability to update the API specifications without having to change the structure of the back end. This can allow for much more rapid updates to the overall API schema without having to change the inner-workings of the core code.
Customer support. Not every API management platform has customer support tools or developer dashboards, but these are two crucial features to be aware of if you intend on releasing your API to the public. Providing a way for your end-users to easily manage their API clients and receive support is important when it comes to the public perception of your API. On the flip side, a platform that empowers your customer service team to independently help users goes a long way toward freeing up engineering resources and reducing sprint creep.
Perhaps the most important decision you can make when purchasing an API management platform is the type of implementation. The implementation method will determine critical things such as how your API manages authentication methods, deals with traffic spikes and automates infrastructure changes. Depending on the infrastructure of your core API, much of this functionality might already be in place, so it is crucial to understand the impact of each type of implementation before making a decision.
There are three methods of implementation:
Off-site. An off-site (i.e., cloud) implementation is by far the quickest and easiest way to get started with an API management platform. By proxying requests through to your internal API, this type of implementation will have the least amount of impact on your engineering team, while also providing the caching, throttling and scaling features already mentioned. This is an excellent implementation method for testing the waters of an API management platform without making a large commitment.
On-site. On the flip side of the implementation method coin is on-site implementations. Because on-site involves installing an agent directly within your infrastructure, this is much more involved and will have a larger impact on your engineering team. If the speed of your API is a serious concern, then an on-site option will help reduce the latency associated with an off-site proxy. Another feature of on-site offerings to consider is user privacy. By removing the off-site proxy, user data isn't passed through a cloud server before reaching your internal API. One big on-site drawback is that scalability and caching is limited by your own infrastructure.
Hybrid. A hybrid platform is definitely the best of both worlds, providing the scalability and caching of an off-site proxy, while utilizing an on-site agent for security and authentication. There is very little difference in the level of impact on your engineering team between an on-site and hybrid offering, as both require installing an agent directly within your infrastructure.
It should be noted that many of the API management platforms that offer an off-site implementation also have an on-site option as well, which will allow you to start off site and then integrate more fully with the platform later on if necessary.
Purchasing an API management platform is a big decision -- one that will affect nearly every member of your organization. While the development and operations departments are obviously the most affected, it is important to consult with your customer support, marketing and sales departments as well.
Because many API management platforms come with a significant number of tools for nontechnical employees, you should take into account the amount of training needed for members of your organization. Your support staff will need to understand how to diagnose and collect data about user issues, while your marketing and sales departments will need to be trained on the features and usability of the public API itself.
With this information in mind, you can now move forward with deciding which API management vendors offer a product that best meets the needs of your organization.
What roles do APIs play in software-defined applications and infrastructure?
APIs are now for everyone, not just Silicon Valley giants
Communication is crucial when managing API versions