February in JBoss

Another month just went by and it is time to wrap it up with the monthly JBoss news blog post. We’ve all be busy thinking about how to make developers life much easier and published a number of articles, blogs and examples on how to get the most out of JBoss products and projects. As usual, this post tries to highlight the best of the best and I strongly recommend to follow the JBoss Weekly Editorial for a more timely update on what’s happening in the community.

Continue reading “February in JBoss”


Building great APIs, part III: The need for API management and infrastructure

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:

  1. 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.
  2. 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 ApigeeMashery 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.


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.

Read more

Building great APIs, part IV: Great developer support

This is part four in our “Golden Rules for Great APIs” series (see links at the end of the article), and it tackles a subject which is very easy to pay lip service to but very difficult to deliver on:

Provide great developer support!

This is a challenging topic since great support is hard to pin down and has that “you know it when we see it, but kind of hard to define” type of quality. When trying to pin it down, it would be easy to put together a list of buzzwords (timely, friendly, to the point, etc.) and leave it at that. Beyond this, we also typically think of support as purely the human interactions which we experience when requesting support. However, beyond these, potentially it helps to think of API support first and foremost from the point of view of the customer (the developer in this case):

As a user of this API, support is everything that enables me to get my job done, to be successful, to ship

In other words, what developers ultimately care about is shipping the Apps in as painless and efficient a manner as possible. Often there might also be more than one API involved – making it doubly important that each one has a quick effective pathway to success. From a support perspective, great APIs need to:

  • Allow developers to make rapid progress – i.e., “it took me 15mins to start pulling results and make magic happen in my App – awesome!”
  • Have self-serviceeasily navigable help documentation when things aren’t quite working – i.e. “Couldn’t figure it out immediately, but I searched the help and these two forum posts solved it – no need to call anybody!”
  • And… lastly, If these fail, they have knowledgablefriendly and responsive support team members who can fill in the gaps in a timely manner – i.e. “Joe from support got back to me right away and solved my problem.”

Although the last item is what one might most obviously think about as being called support, in fact all of these form a hierarchy of helping the developer reach their end-goal shipping. Being faced with situation where the only resolution is a phone call is a blocker, having to wait 3 days for an email from support is a blocker. Clearly the human factor in point 3 – how friendly and accessible are support team members are – is important in people’s overall perception of the API, but even if the support team is outstanding, having to call them time and time again just to inch forward on an implementation will still leave a poor impression (not to mention wear out your support team!).

While we try to give an overview here, there is a wealth of good material out there on how to support API Developers – API Evangelist is a great starting point. Also see Brandon West‘s great summary on Support/Docs and what elements are needed.

Types of Support

Before digging deeper into concrete aspects, it’s important to acknowledge that for APIs there are generally two types of support needed for an API:

  • Development time.
  • Runtime.

Discussions of support tend to focus on the former: helping developers write their applications initially and complete their integration. Certainly this is a crucial step and where the learning curve is the steepest. However, once integrated, using an API means an ongoing relationship – outages, slowness, changes etc. in the API potentially affect integrated applications at runtime when the developer using the API is not expecting issues. API outages may take down dependent applications, so it is critical to ensure support is available to respond to runtime issues as well as integration time issues.

It may also be the case that different teams in your organization will be responsible for different elements of support – typically run-time support will require an ops-team. We won’t cover this extensively in this post, but it needs to be planned for (and the post on API Management covers some of the tools and processes they may need).

The Non-Human Elements of Support

As mentioned in the opening, support is not just about the human element in the loop (team members responding to queries) but the overall experience of “getting things done” with the API. Given that a developer’s main objective is to get a job done quickly and painlessly, the more can be achieved without waiting around for human intervention the better.

The following items should be high on the list:

  • Concise Descriptive High Level Overview Documentation: a brief but informative description of what the API actually does – what kind of applications can be written and what kind of use cases are covered. This isn’t typically required by the developer once the API is being used by anger, but it is very important early one when developers are deciding whether to dig in or not.
  • Clear Comprehensive Reference Documentation: high level is not enough however if there is a real job to be done and the next critical item is a complete reference guide to the functionality on offer. This is important since it forms an essential description of the toolset available and helps the developer find exactly the right method for what they are trying to achieve.
  • Interactive / Sandbox Tools: A relatively new but important addition is the provision, where possible, of some form of interactive sandbox that allows developers to write trial calls to an API and see the result. There are tools available such as Swagger (which 3scale supports automatically), I/O Docs and Apigee Console. Each of these has a slightly different take on how to structure and maintain the sandbox but all serve essentially the same function: enabling the testing of calls without having to write code.
  • Code Samples: a further, very powerful, type of documentation (see highly regarded APIs such as Stripe and Twilio for example) is the use of code samples – small snippets or even extensive downloadable libraries that illustrate how to achieve a particular use-case. These can save developers a lot of time and help make the abstract potential of the API appear to be a lot more concrete. Code samples take a lot of effort to prepare but are genuinely worth the effort many times over in helping developers help themselves.
  • Forums, Comment Threads and Discussion: unless your API is operating in a very controlled environment where third party comments are unwelcome or not possible, forums and comments are a great way to make the user community come alive and participate in support. Having message boards on which users can pose public questions and either the support team or other users answer them both enables people to engage and keeps answers to questions building up in a shared knowledge-base in a way email does not. Forums clearly have their own cost in terms of moderation and a commitment has to be made to provide timely responses, but the community engagement possible will likely repay this cost quickly.
  • Inspiration as well as education: Developers will often come to an API with pre-conceived ideas of how it will work (based on what they’ve seen elsewhere) and may then churn through with this mindset. So providing examples and snippets about what is possible (shortcuts, special features, deviations from the norm) can both save frustration and potentially enable them to do things they did not know where possible at the outset.

Human Elements of Support

However good your self-service information is, Humans are still needed in the loop. Support roles in technology-driven companies are sometimes perceived as unglamorous or “second class” to mainline engineering or marketing/sales. It is hard to know where this bias comes from, but in the API World allowing this perception to hold is both very wrong and probably a recipe for failure. In addition to the many general reasons why a powerful commitment to service as a culture brings great benefits (Tony Hsei’s Zappos story is inspirational), for APIs valuing the support function is even more important:

  • API Support is requires coding skills: it will generally need individuals who are both able to communicate well and able to write code in order to genuinely help developers – finding talented people in this regard is highly challenging.
  • API Support requires complex out of the box thinking: APIs are effectively a “Swiss Army Knife” of functions that enable a wide range of use cases – and support team members will have to be adept at discerning what the developer is trying to achieve and understand how to deliver it.
  • It is an 80:20 world (or is it 90:10?): it is likely that the most (20%) successful integrations of your API will drive very large volumes (80%) of the business that will flow through the API – making sure these integrations run smoothly is a hugely critical task. Further, the support team needs to be able to determine which integrations will be most important and ensure these succeed, whilst providing a still friendly service to the remainder.
  • Tech influence in purchasing is strong: When it comes to APIs, more so than with other types of IT products, technical staff (developers) typically have a large role in deciding which solution to go with since they will be in charge of execution. A big factor in the way they will swing is likely the level of trust that they place in the capabilities of the support organization.

As a result, API support teams are an integral part of customer success and ultimately also part of the marketing/sales process. Great support generates more success and more happy customer stories.

Taken together, all this means that it is very important to find the right type of team members to serve in these roles:

  • Passionate: about your company, the API and helping customers succeed.
  • Technically Competent: able to engage developers as a peers.
  • Curious and Interested: in what developers are doing with the API and learning more about the potential of the API.
  • Attention to Detail and disciplined: able to follow up and ensure things are carried out when they need to be.

Working with customers on App rollouts using an API can, in many cases, be more exciting and varied than working in the core engineering organization. So hopefully thoughtful, passionate people in your organization will step forward!

It may also be that a blend of different roles is needed – from a more standard technical support role to something more akin to an “API Evangelist”. The later is a new role which is emerging that typically involves more than standard customer support and tends to add in: public speaking about the API, attending hack/coding events to represent the company and potentially also going further in terms of thought leadership about technology / what can be done with the APIs. It may also be that everybody on the support team takes on somewhat of this role. Again see API Evangelist and other web resources for some great resources on this topic.

Additional Factors

The pointers so far have been relatively “support” specific, but there are a number of other factors to strongly consider that significantly affect how API support is executed within your organization:

  • Good API Design: APIs which follow standard conventions for whichever world they are from (SOAP, REST etc.) are more intuitive to developers and require less head-scratching before progress can be made. This in turn increases the amount of self-service success that developers can experience – reducing human support load. While there may be perfectly good reasons for breaking standard conventions, in places where there is a choice “ease of use” should likely be one of the decision factors.
  • API Stability and versioning: related to the first point – one of the most confusing elements of most APIs is when multiple versions of the API exist in parallel, when new versions are released and it becomes unclear which version is in play at a given time. Long term thinking, good communication and stability on the API go a long way to reducing support burden.
  • The Right People: already mentioned in the previous section, ultimately the human element will always play a role in the success of the API. The more dedicated, passionate and effective the support team, the better the results will be – and their enthusiasm will add an infectious desire on the part of developers to work with your platform: possibly better than your best marketing in promoting uptake.
  • Community Support: when resources for support are limited, a powerful effect (if it can be created) is for users of the API to support each other via (for example) forum posts and tweets which answer support questions before your support team can reach them. This kind of dynamic is wonderful when it occurs but it can be difficult to kick start – in our experience, at least 1-2 dedicated team members are needed to set the tone and always be willing to dig in to issues which the community cannot answer. Community advocates can typically act as a “multiplier/amplifier,” but it is rare that they can carry the entire burden.

The Value of Great Support – your best API Marketing Channel

Great support has a cost – both in tools/content and in hiring great team members to interact with users. Often this cost seems hard to justify since it seems outwardly to be more of a cost-center than anything else.

The impact of great support for an API typically plays out in one of the core business metrics that likely needs to be tracked: conversion rate from interested developer to live application/customer or something similar. This metric is often treated as secondary to the raw number of sign-ups for the API but it shouldn’t be – it is arguably even more important. At a more fine-grained level:

  • How many implementations are successful?
  • How long did they take from sign-up to go live? Could this time have been made shorter with better support?
  • How much “talk time” is needed with support team members? – could some of that have been avoided with better documentation (which in turn would reduce recurring cost to the support team).

The second dimension in which great support pays off is positive public sentiment about the API and word of mouth. The following are example tweets about some of the best-known APIs (these are both from today – searching for other top APIs quickly also produces numerous results):

and the rather timely tweet:

Although it is hard to gauge the exact impact of this, it is very clear that such public advocacy is one of the most powerful forms of validation for adoption of your solution. Just as Rackspace focused on “Fanatical Support”, commitment to excellent support for your API can reap rewards.


It is hard to imagine a truly great API with poor support. While it’s possible that an API may be very intuitive for developers and technical help required is minimal – at least a minimal engagement from the API provider is needed to set the tone, smooth over corners and build confidence in the platform.

The best APIs truly excel at support and put in place both automated and human mechanisms to make sure developers can succeed. Ultimately, support for the API needs to be a first-class citizen in the planning process and not an after-thought or a cost center to be minimized.

Coming up

In the next post, we’ll tackle the last of the 6 golden rules – scalability and reliability: an API that’s great in all other dimension but performs poorly falls at the last hurdle!

Read more