In previous parts of the series, we covered the need for APIs to be valuable, have business models, and be easy to adopt. In this post, we’ll cover the next items on the list: API management and API management tools:
- The API should be managed.
What does this mean? And why is it important? Before getting started, we should acknowledge that 3scale provides tools and infrastructure to do exactly this, so this might appear self-serving. However, there are multiple ways to put API management in place—not just using a third party, so we encourage people to explore what’s best for them whether it be home build, open source, with a vendor or a combination of the these. Having said that you can give 3scale’s tools a whirl free to test them out!
What does “Managed” mean?
An API is a window onto data and functionality within an organization—enabling developers to write applications that interact with backend systems. Just as this is extremely powerful, it also creates a complex set of dependencies between the systems provided by API Provider and those built by the users of the API:
- Changes on the API may require changes to Apps.
- Different people may need different levels of Access to the API.
- It’s likely important to know what usage the API is getting, from who and when.
- There are very often business relationships associated with usage of the APIs (ranging from a simple Terms of Service click-through to a complex negotiated contract).
- Over time, the API needs to deliver certain levels of service in order to be usable by its audience.
Hence, while an API in essence starts life as “just a technical endpoint,” once it sees use, the API Provider’s responsibility towards users quickly grows. An API without clear answers to questions such as:
- Who has the right to use it?
- What rights exactly do they have?
- How do they get access? (and how is access removed?)
- What service levels can be expected?
- How is the API secured?
- How is it versioned?
- How are service issues, changes and issues detected and communicated?
- Are there business restrictions to usage?
- Are there charges for usage?
- Are there SLAs?
will likely not be viable for third parties to use (the risk is too high that the sand will shift and their investment in apps lost) and spiral out of control in terms of operations costs for the API Provider—if operations are not tracked, security, load, support and other issues can overwhelm the team responsible (possibly leading to the API being shut down again!). This is even true if an API is for internal consumption only—having an endpoint which is used within a company but which doesn’t have the minimum of monitoring and control around it is a recipe for nasty production surprises.
Just as no reasonable web site today is launched without infrastructure in place for security, performance monitoring or analytics, tools are needed to keep APis operating effectively and these form the basis of API Management.
The Elements of API Management
While there are different takes on what is “in scope” for API Management, we’ve come to think of it as covering two clear areas:
- Technical Operations Management: the tools necessary for visibility and control of the technical functioning of the API – keeping it secure, controlling who has access, rate limit enforcement, kill-switches, load management, performance monitoring.
- Business Operations Management: the tools needed for visibility and control of who is using the API and how – issuance of access rights, usage analytics per partner / developer and application, management of bundles of rights for different target audiences, workflows for API user signup, assignment and changes of rights, integration with existing business (customer or partner) relationships, user and community support tools around the API.
Together, these two levels ensure that the API functions correctly and is secure, but also that 3rd parties can engage with the API in the right way. Notably, the two levels generally also relate to different team members on the API Provider side – the operations layer typically corresponds to tech/web ops teams who are tasked ultimately with systems stability. The business layer typically addresses the needs of business development, sales and support teams as well as others involved with helping API users be successful in their implementations.
While the precise systems that are critical vary for each individual API, we typically see basic systems needed as a minimum to cover the core of technical operations and user engagement. Even if an API is not for commercial usage, it is often still imperative to know something about who is using it and how:
- Good API analytics often throw up usage anomalies (“did we design the API right here?” – “is this app abusing the ToS?”) and also help understand the utility of the API to users (“how should we evolve?”, “how can we justify the value of the API to other groups in the company?”).
- Good mechanisms for user signup increase the speed with which new users can get started (see Jeff Lawson’s great slides on appealing to developers) and also create critical communication channels in case things go wrong or service messages need to go out.
- Good monitoring, security and rate limits help ensure that the API systems stay within their operational envelope and keep delivering consistent services to users – without which applications may suffer.
- For paid APIs, up front thinking of how API Users will pay for the services and under what terms is something that was already discussed in a previous post – ensuring such systems are as automated as possible helps save large amounts of team time later in the game.
Lastly, APIs over time form part of a company’s core business strategy (see some common business models here and here). As such, the API management layer should expect calls from different departments for integration with their systems—CRM, BI, General TechOps, Management dashboards, etc. Poor instrumentation and control at the API layer will often mean less API success, simply because the impact of the API can’t be seen or related to success of the business elsewhere.
From a functional perspective, the key most basic features often needed for API Management include:
- Access Control: authentication and authorization systems to identify the originator of incoming traffic and ensure only permitted access.
- Rate Limits and Usage Policies: usage quotas and restrictions on incoming traffic volumes or other metrics to keep traffic loads predictable.
- Analytics: data capture an analysis of traffic patterns to track how the API is being used.
As the API becomes more sophisticated, several other API management tools and features quickly become critical – which are most important typically depend on the API:
- Monitoring: regular test cycles and alert systems to check systems are functioning as expected and in their operational envelope.
- Logging: capture and analysis of system log information to provide deeper information on system usage and aid in issue detection.
- API User on-boarding: systems to enable API users to signup to use the API, receive access credentials and to be assigned the correct user access rights.
- API User Management: managing user permissions and tracking usage across the whole lifecycle of a user accessing the API, deploying applications through to retiring them or having access revoked.
- Versioning: mechanisms to roll out new versions of the API to users and allow them to migrate applications and/or detect/switch between prior versions.
- API User Support and Engagement: documentation, forums and other channels to provide API User support.
- Usage Billing and Payments: for those APIs that charge for access, support for the implementation of the business model needed by the API – e.g. monthly fees, utility style billing, credit systems or similar patterns.
Delivering API Management
Having looked at the functional needs, questions arise on how to deliver on these – and also when to do so? The When is covered below but first we look at how. Implementing a well functioning efficient API is challenging enough without having to set up many of the additional management features and it’s unlikely to be a task many look forward to. To complete the task effectively and put a good system in place there are several possible solutions:
- Using a vendor infrastructure or product like ourselves (3scale): this provides you with an extensive tool set out of the box and a well-integrated solution.
- In House Build: in this case, custom software is developed to deliver the management systems and this can be valuable if and when there are needs very specific to the API that aren’t supported by third party solutions or open source.
- Open source tools: selecting from a number of open source system which implement components of the API management stack and are either API specific or can be repurposed from other non API use cases.
- A mix of the above: lastly, since there is often not a one size fits all solution, tailoring a set of tools from what is on offer may be the best option.
We’ll dig into each of these options a little further.
API Management Vendors
At 3scale our aim is to provide the right infrastructure services for APIs out of the gate and provide great coverage of many of the areas discussed above. The solutions also start at free and scale up to very high volume enterprise deployments. The solutions typically cover all the core elements of operational and business control + provide multiple ways to integrate into the API flow.
If nothing else looking at the solution set can be useful to determine what to put in place.
There are also other vendors in the space including Apigee, Mashery and, WS02 each with somewhat different approaches.
In House Build
Custom builds for API management components typically involve tailoring software to a specific API data capture or enforcement need and then adding the appropriate interfaces. As APIs have become popular companies choosing this path have typically added significant numbers of custom layers to fit their business successfully.
This path fits well if there are specific needs to be met that aren’t easily covered by open source or vendors. We see this path taken less often now than in the past since vendor offerings / open source have improved and gotten more cost-effective. Often, custom code might be a part of the API management solution but it is rare to see a complete build of all systems.
Open Source
At 3scale, we see as part of our mission to enable as many people open APIs as possible and hence it’s exciting to see open source solutions starting to become part of the API Management playbook. Some of the most notable are API Axle (which provides an API proxy), WS02’s API Manager (which provides traffic policies and onboarding), the Swagger toolset(which provides API description formats and documentation rendering) as well as our own NGINX based traffic management gateway (which provides traffic flow control).
There are also generic open source tools which provide high value to APIs including web proxies, open source monitoring tools and many of the programming frameworks that now make it easier to write well structured APIs. While these do not provide API Management per-se they provide a good baseline for custom extensions or hooks into other systems.
A Blend of the Above
Lastly, in many pragmatic deployments the best solution is a blend of the above, with a number of components chosen to fit together the API stack – this gives the API Provider tight control of exactly the system they wish to run. Typical configurations might include:
- Selection of vendor as the core system + a number of open source elements or custom builds to add functionality or integrate with existing systems.
- Usage of an open source traffic management system + adoption of vendor or custom tools to support reporting, analytics, etc.
- Custom code integrated into the API stack for traffic management + vendor/open source components for managing business level elements, such as user on boarding.
Conclusions
This post might suggest that you need a mountain of new complex systems before even getting started with an API, but that’s not necessarily the case. When starting out a text file of valid keys + some logging might be perfectly ok to enable what’s needed – there’s no need to add complexity for no reason.
As the number of API users and its importance grow, however, it’s important to begin to answer questions about the onboarding process, guarantees given and how users are supported. Without a good handle on traffic operations and engagement, operational complexity can quickly spiral out of control.
Getting at least a thin management layer in place early is highly valuable in scaling up usage of the API. The management component is likely to be a significant part of the API experience for its users, so it pays to have something in place early.
Next Up: Great Support
Ultimately, the main reason management systems and an API management tool are so important is for the API Provider to stay on top of delivering the service to users of the API. Having a well managed technical endpoint and issuing keys is still only part of the story though. Great APIs help people get things done—that’s where great support comes in, which is next up in our series.