Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage Articles Making the Case for an API Roadmap

Making the Case for an API Roadmap

Business and IT teams desire to extend business capability reach across new geographies, distribution channels, devices, and demographic groups. RESTful APIs are tried and tested technical glue that binds business capabilities with internal and external consumers, and creates a scalable and maintainable foundation to connect the world and extend business reach. But REST APIs alone do not address key security, quality of service, ownership, and lifecycle challenges. Development and architecture teams must craft roadmaps and execute playbooks detailing best practices, infrastructure, and operational processes that will reliably deliver APIs as a product and maximize consumer adoption.

An API roadmap must enhance the team’s ability to deliver operational reliability, streamline governance, manage requirements across diverse customers, and increase API adoption. Software architects and developers can take seven actions to avoid common API pitfalls, create business value, and monetize API assets:

  • Embrace the Managed API
  • Make APIs Easy for Developers to Access
  • Participate in the API Economy
  • Employ Governance
  • Monitor API Use
  • Build a Brand
  • Take a Product Perspective

Embrace the Managed API

Successful API roadmaps address security risks, operational concerns, lifecycle challenges, adoption hurdles, and ownership dynamics by promoting ‘Managed APIs’. Managed APIs represent ‘SOA and integration done correctly’. A managed API is:

  • Actively advertised and subscribable
  • Available with an associated, published service-level agreement (SLA)
  • Secured, authenticated, authorized and protected
  • Monitored and monetized with analytics

Managed APIs increase adoption by establishing operational visibility and creating a trusted provider-consumer relationship. API management systems automate quality of service (QoS) enforcement, secure and protect the API, monitor usage, and manage access keys.

Key management provides a unique key ID for each API subscription. The key supports tracking, reporting, and taking corrective action. If a subscriber overloads the server, the key can be revoked, or the enterprise can charge additional subscription fees for the higher usage rate.

While all services should exhibit managed API characteristics, most service endpoints are deployed on platforms that don’t deliver management characteristics. By applying the API façade pattern, teams can layer network addressable endpoints, monitor usage, enforce usage limits, shape traffic, and authorize consumers.

Make APIs Easy for Developers to Access

Access is often a significant API adoption barrier, so provide a self-service, resource-rich environment. Use API management infrastructure (e.g. WSO2 API Manager, Apigee, 3Scale) to expose an “API store.” The API Store application will establish your own API marketplace and promote APIs. Application developers easily find, explore, subscribe, and evaluate APIs within a marketplace experience similar to the Apple AppStore or Google Marketplace. The venue lets developers register as a potential API consumer, obtain API access credentials, and match project requirements to API capabilities.

Well-organized support channels and API documentation enable developers to “try before they buy.” A structured API exploration environment rapidly reduces the time and effort required to evaluate and integrate API resources.

Participate in the API Economy

Business teams want to expand revenue, accelerate customer acquisition, and increase customer retention by offering new products and decreasing interaction friction. APIs offer low friction delivery channels and create valuable information or process streams. The ‘API economy’ refers to new business models, opportunities, and revenue streams created by APIs.

API Economy metrics include API consumer adoption and usage. API governance practices help establish processes, policies, and metrics that quantify API adoption and usage. By understanding API adoption and usage (both by API model and API version), API business owners and API architects can intelligently invest future development resources, properly plan API infrastructure scale, and rationalize the API portfolio.

In addition to understanding how APIs drive business connectivity, API roadmaps can also drive new revenue streams. Before exposing an API, determine an appropriate monetization model. Monetization will affect API availability policies and monitoring techniques.

Some companies, (e.g. Urban Mapping and Xignite) charge per API call or business transaction. Microsoft recently announced a hybrid model for its Bing search API; the first 5,000 API queries each month are free, and then charges accrue. Alternatively, some API providers charge based on business service access. For example, the provider charges a flat monthly subscription tied to an eBay storefront.

Not all APIs are monetized based on a currency amount. APIs created for internal use may not map to traditional revenue streams, but rather optimize internal processes. An API provider can “charge back” or “show back” business value based on adoption and usage. For example, the provider may communicate value when 15 other departments in the organization made 3 million calls against an API during 2013.

Employ Governance

It’s not enough for APIs to be readily available. When publishing an API for consumption, governance keeps the environment from devolving into chaos by managing people, policies and processes. API management systems enforce operational controls on essential development lifecycle functions, API versions, and runtime technologies.

For example, a team may desire to enforce a specific message payload or interaction pattern. If an API maps back to a mobile phone, a team might want to encourage a simple JSON format and minimize the number of interactions. By contrast, efficient machine-to-machine interaction may require larger transferring larger datasets via XML payloads. Knowing the consumer and applying design-time governance fosters creating the optimal API interface.

API governance is heavily influenced by IT business goals and objectives. Leading API governance platforms provide analytics supporting the assessment of IT business value. The platform should capture service tier subscription information, collect usage statistics, present productivity metrics, and integrate with billing and payment systems.

API governance encompasses API subscriptions and API promotion meta-data. Governance activities managing API promotion meta-data include rationalizing keyword tags used to categorize APIs and managing developer documentation content. The governance process should enforce design-time checkpoints before API publication.

Monitor API Use

Effective API monitoring compliments governance. The best API ecosystems and platforms include measurement tools, metrics, and activity repositories that report back on usage, ecosystem traffic, and referral traffic. Requests and response metrics are germane to understanding how the API works, identifying emerging request trends, and evaluating responsive delivery. Failing to measure and analyze API usage on a daily or weekly basis will inhibit creation of a reliable API and vibrant API community.

By combining usage insights with robust governance and an attractive API storefront, the enterprise is well positioned to build a community, increase API adoption, realize monetization goals, and maximize API value.

Build an API Brand

A well-executed API brand strategy helps your API stand out from the crowd, encourages API adoption, and increases business growth. API brands enable you to build mindshare with your target audience. Mindshare increases API visibility; visibility encourages individuals (and devices) to discover and evaluate your API. API evaluation triggers API adoption, and adoption realizes your goals (i.e. increased interaction and revenue growth). Figure 1 illustrates the virtuous API branding cycle.

Building brands requires art, science, and execution. Brands are a blend of consumer perception and provider reputation. Consumers associate brands with commodity, exclusivity, ease of use, and value. A provider’s reputation is built by constantly delivering required capabilities and data, API quality and warranty, and delivering customer service through available support channels.

Build an API brand strategy by:

  • Defining the API brand message
  • Building API brand awareness
  • Nurture the API brand
  • Measure API brand value

When defining the API brand message, identify the target audience and specify key perception targets. API brand awareness requires continual communication, promotion, and visible outreach actions. API perception and reputation are nurtured through partnerships, community relations, and education. Consider tasking a group to be API advocates. Awareness and nurturing activities require significant time and effort, validate the strategy by comparing adoption, retention, and revenue growth with API alternatives. Good brand success metrics can be obtained by tracking market interest and third-party coverage.

When establishing your API brand, focus on value, perception, reputation, and retention building blocks. For example, value is created by delivering the right message elements and attributes, aggregating API endpoints, orchestrating API interactions, and delivering service tiers at reasonable cost. Quality delivery and ease of use will influence consumer perception and provider reputation. An API brand is impacted by service level agreements, Terms of Service (TOS), available case studies, number of partners, and available documentation (including client samples, SDK). API brand activity increases retention by highlighting integration with other useful APIs and promoting the API through logo usage policies.

Continually promote the API brand identity by requiring attribution by consumer apps and websites. Develop a ‘powered by’ logo and embed scripts. Make the API a subset of wider functionality that is available when the end-consumer establishes a direct relationship (see Zillow branding guidelines). Retain API exclusivity, monetization potential, and brand control by requiring consumers to present authentication keys and establishing terms of use. The terms of use should disallow message manipulation, modification, or edits. Authentication keys, rate limiting, and quotas enable you to adjust revenue with end-user value.

Because an API brand relies on consumer awareness and perception, nurture the community with a partner program to reinforce API value. Use hackathons to build an ecosystem and gauge API usability. When expanding the API’s reach, tailor the brand message to diverse communities.

Because perception and reputation are incrementally acquired and persistent, building a name brand requires significant foresight. Before investing significant time and effort promoting your brand message, answer the following questions:

  • Who will own the customer relationship with the API end-user?
  • How will you increase brand awareness?
  • How will you prevent API commoditization?

Balance your desire to syndicate the API across third-party developers with API monetization power. Place 3rd party attribution and reference guidelines in place before making your API available, and using ‘see more’ attributions to drive the end-user towards your brand property. Prevent commoditization by executing a plan to aggregate and orchestrate multiple capabilities (i.e. deliver a solution instead of a building block) and tap your API into a broad ecosystem of complementary providers.

Look and feel strongly influences perception. Build a developer and end-user portal that matches your intended audience and desired brand image. Choose an API brand platform where you can customize the portal.

Take a Product Perspective

Delivering API products instead API projects requires a mindset shift. Teams must understand client business goals, promote a cohesive API product portfolio, and efficiently evolve the API. A product mindset shift focuses on API warranty, packaging, and evolution.

Warranty refers to the API’s quality of service, scale, and longevity. Packaging outlines the API boundaries by defining business capability, tiered service levels, and appropriate contextualization. Evolution is a product management concern, and an API product evolution may exhibit rapid releases, disruptive API shifts, or devolving feature bloat.

Successful API products achieve significant reach, impact, and revenue. Teams can measure reach by counting the number of consumers and transaction breadth. Teams measure impact based on aggregate usage or usage per consumer. Revenue is often trickier to measure because it may be indirect and margins (operational or net) can be hidden across multiple expense and revenue centers.

You can extend your API product’s reach by carefully crafting API descriptions, augmenting API context, and embedding personalization.

APIs may be one-size-fit all and focus on popular demand, or tailored to enable the long tail. Micro-context tailors information delivery based on specific individual wants, needs, and capacity. The micro-context of a vacationer’s request in New York City is very different from a request posted from a remote beach in the Bahamas. Context drives a pull economy, where API consumers can find and access a custom designed API. Instead of API providers specifying API response, API consumers drive interactions and content.

Consider adapting your API response based on consumer goals, interests, objectives; requirements and constraints; or available consumer resources, such as the consumer’s manpower, physical tools, or financial position.

API behavior and responses can be personalized per caller. Common API personalization dimensions include:

  • Information access privileges
  • Information aggregation and composition
  • Social network access privileges
  • Business processes and rules
  • Service levels and Quality of Service
  • Security policies
  • Monetization rates

Take Your First Roadmap Steps

When taking your first roadmap steps, create a pragmatic, ninety-day plan that blends technical and business actions. Focus effort towards implementing infrastructure that facilitates easy developer access and managed API deployment. Work with business stakeholders to quantify how APIs fit within the API economy and how an API brand will increase revenue, customer acquisition, or customer retention. Collaborate across DevOps team members to create a governance playbook and API monitoring scheme that streamlines processes, accelerates business delivery, and efficiently identifies business productivity.

About the Author

Chris Haddad leads platform evangelism at WSO2. He lives in Space Coast Florida, where he watches rocket launches, rides the ocean surf, and writes about architecture best practices. Chris converges pragmatic hands-on practitioner experiences with IT business goals to communicate strategies and tactics when adopting Cloud, DevOps, and API-centric architecture.

Rate this Article