{"API Evangelist"}

A Framework For Our All Day API Discussion

This is an outline I pulled together for a potential project I am working on this week. It's derived from my research, and previous workshops I've done with companies, organizations, institutions, and government agencies in the past. I wanted to share here, in hopes it would stimulate API-focused conversations with some interesting folks.

I put together a framework to guide a full day discussion between us, which will leave you with a greater awareness of what an API focus can bring to your company, and leave you with a strategy that you could apply to your API operations back home. This framework is assembled from the last seven years of monitoring the API practices of leading companies like Amazon, Google, Facebook, Twitter, and others, but tailored to meet the needs of a retail and digital commerce focused company. I don't expect you to digest everything here in a single reading, it is the complete list of building blocks which we will move around, and organize in a guide for you to take back with you.

API 101
I wanted to start with the basics and help provide you and your organization grasp the fundamental concepts of why having an API focus is important to doing business in 2017. It is important that all stakeholders have a base level awareness of the what and why of APIs are, as well as the technical, business, and legal implications of API operations. Here is an outline for our discussion:

Before we dive into the details of modern API operations I want to make sure we have a solid base for understanding why your company should be investing APIs. Then we can talk about what else will be needed to do this successfully.

Definitions
Before we get started, let's define the building blocks of doing APIs, starting with the high-level objectives of why your company is looking to do APIs. Then we will move from the 100K level, and identify some of the common building blocks we'll use to define API operations across all the working areas below.

All of these areas touch on and will guide our discussions throughout the day. The definitions will guide our conversation, and then also become a core outline for governing API operations at every stage of its development--defining the design, deployment, management, and every other area of operations.

Design
A design first strategy is needed to achieve consistency, and maturity before we enter the more costly phases of development and deployment. There are many common approaches to API design on the web, and these are the common areas I'd like to discuss as part of your operations. 

Your API design strategy will evolve and mature with time, but setting a healthy base for operations will help set a tone for API operations. How you design your API resources, will affect how they speak to your partners as well as 3rd party developers, and contribute to the overall success or failure of internal and external API consumption.

Versioning
I want to discuss the high level of how things will evolve across API operations. Your web and IT development already have established cycles and workflows. How will these apply to API operations, and what are the key considerations when it comes to API versioning, and all applications that consume them.

It is necessary to discuss versioning in a technical and business sense. Better understanding how things will change and evolve, and being truthful and honest about how this change impacts operations, integrations, and each application that touches API operations.

DNS
You already have DNS in place for your web operations. We will be taking a look at what is in place, as well as discuss the front line for API operations. DNS provides the base URL for API access, as well as human access for the overall API operations. 

There is already DNS infrastructure in place, this is a discussion around what is required to deliver and support API operations. As with the web, DNS is the frontline for the presence of the API operations, and we need a snapshot of the role it will play in API operations.

Data
I would like to learn more about all of the data sources for your operations. Where is data stored? Where does it come from? What is the complete picture when it comes to data and content accessibility? We can cover a handful of areas to help paint a picture of what is currently behind operations.

Not all APIs will be about delivering data, but a significant portion of APIs will be data or content driven from a myriad of sources. I need an honest perspective of the data landscape behind. Opening up APIs shouldn't just expose everything behind, it should be thoughtfully composed, providing the best possible view of the database backend.

Deployment
Next up is the actual deployment of APIs. Discussing how APIs are deployed, building from the database backend that is available, and moving forward to look at many of the common ways APIs are being deployed today. These are some of the common areas we'll discuss:

These areas represent the current API deployment stack, providing the framework for our discussion when it comes to publishing APIs. How you are currently deploying web infrastructure will significantly impact this discussion. However, I'd like to also introduce you to other approaches to deploying APIs, so that you can consider the future of your web and API infrastructure.

Environment / Virtualization
APIs are rarely deployed directly into a production environment. Leading approaches to API deployment involve a variety of virtualization techniques for underlying infrastructure, the APIs themselves, and possibly even the data, and content they serve up. These environments will provide solutions to mock, simulate, conduct quality assurance, production, and other approaches to staging API deployment.

This are might seem like a nice to have a category, but in reality, API and data virtualization can significantly lower the cost of deployment and management and rapidly increasing the rate of maturation of API resources. Different APIs will have varying virtualization needs, let's consider what is needed, based upon your goals with API enablement.

Authentication
Let's take a quick look at what is needed regarding platform authentication. Looking at internal and partner needs first, but then also considering the 3rd party, and authentication using popular social platforms like Facebook, Instagram, or even Github for developers and more technical user. 

There is a common toolbox for enterprise applications. There is also a common set of authentication practices for web APIs. The goal of our conversation will be to set a baseline for this overlap between what you currently have, and what will be needed to deliver API resources across web, mobile, and device applications, in as frictionless a way as possible.

A Portal 
Where will internal, partner, and public users find API resources? It is common to have a central portal to find all APIs and supporting resources can be found. Providing a focused presence and voice for an API, encouraging the awareness and usage of common APIs across company operations.

Portals can be permanent, or ephemeral. They can exist in the cloud, on-premise, or on devices. Portals can act like a retail storefront, providing a permanent or tempory snapshot of resources available across the entire platform, in support of a single project or event. Regardless of the objectives, a portal provides a single doorway into API operations.

Management
Next, let's walk through the management of API operations. Focusing on what it takes to manage the intersection of providing and consuming APIs. How will engagement be documented, managed, measured, and provide a wholesale representation of the companies existing platform, brand, and presence?

Management doesn't stop here. Each of the following areas will play a role in the management of the platform and have a place in the portal. The goal of API management is to provide a scalable, measurable, observable layer for efficiently managing the technical and business intersection that APIs open up.

Getting Started
First impressions are everything. Let's take the onboarding discussion, and think about it from a consumer's perspective, and establish exactly the right experience for new, as well as existing users. A little bit of discussion ahead of time around what it takes to get started can go a long way. 

It is common to launch an API and think only technical people will be accessing it. In reality, an API should speak to technical, as well as non-technical users. You never know who will be researching your API for a story, creating the curriculum for a university class, or other use that hadn't occurred to you. APIs aren't just for developers--anyone should be able to get started without too much friction.

Documentation
The next step in getting started is always about visiting documentation for an API. API documentation provides the next step after the marketing and advertising that directed a consumer to an API. Let's explore what should be available to ensure all users quickly get up to speed on the details of what an API does or doesn't do.

Documentation is always identified as the number one pain point for developers when it comes to putting APIs to work in web, mobile, and device applications. I will walk you through the advancements made in the area of documentation, minimizing it as a pain point for both API providers and consumers.

Software Development Kits (SDK)
It is common for API providers to provide a variety of language and platform development kits for consumers to put to use. Web APIs are language and platform agnostic and can be consumed in any programming language. There are some common aspects of delivering and management code as part of API operations--let's look at some of the common areas: 

This is where APIs really shine, providing a variety of openly licensed or even premium resources for API consumers and developers to put to use. When you look at the leading pioneers in the space like Amazon, SalesFroce, and Google, they all have a wealth of existing code resources, helping to go from idea to integration as quickly as possible.

Support
Let's talk about supporting API operations. Providing the necessary technical and business support that individuals, companies and any consumer will need when working with APIs in their integration or application--a successful API has a wealth of support resources that scale with the demand.

As with other areas of IT and web operations, API support will overlap with existing services. However, because of the technical nature of API integration, support should include a heightened level of technical expertise, understanding the challenges of API consumers.

Communication
Complimenting support, let's talk about the communication strategy for API operations. This should overlap with existing communication efforts, but if the resources are available, it can be beneficial to have a dedicated API operations strategy and presence.

This can dovetail with existing communication but needs to possess a focused message that speaks to a more technical audience. It helps to provide separate channels dedicated to a developer message, but take advantage of cross-pollination between mainstream and API operational efforts, keeping a message in alignment, and increasing the reach.

Road Map / Issues / Change Log 
One of the benefits of doing APIs is that they can help deal with change and shifts in the development process easier. There are many common ways in which an API helps address change, and evolution, something that is integrated with support, and communication efforts.

Change management is essential to address change for not just the platform, but the many distributed applications and integrations that depend on APIs. Clarity, transparency, and communication in this area will potentially make or break a platform, determining the success of the platform, as well as partners.

Monitoring / Testing / Performance
Let's spend some time talking about the monitoring of API operations, their availability, performance, and assessment of whether or not they are meeting their intended objectives. Some of this will already be in place with web efforts but will need a unique set of considerations when it comes to API operations. 

This are of API operations will help us understand how well we are doing executing the strategy, and meeting internal and partner expectations. Monitoring and testing should be executed as part of every API deployed, led by development groups, but should include business unit, and partner stakeholders in the conversation, notification, and discussions about changes to monitoring and testing efforts.

Reliability
Let's talk about the reliability of the platform, and what will be expected of internal and partner stakeholders. We'll take what we learned in the monitoring and testing discussions, and translate it into business terms, and understand what was promised as part of API operations and integration.

If API resources are to be monetized upstream or downstream they will have to meet the expected level of reliability. Meeting the API contracts in place for accessing and consuming data, content, and algorithmic resources, and justify the money being exchanged for services.

Security
Along with reliability, security will be essential to a successful API operation. APIs leverage the web, but are far from open and available to anyone with the web address. There are many technical areas to consider when it comes to API security, but let's just talk the basics this round. 

We can expand on this area if needed, but I prefer to address a well-defined API strategy as the first step in platform security. APIs help standardizes how resources are accessed and put to use, which goes a long way to help secure valuable corporate interests and protect valuable corporate assets.

Legal Department
Let's make sure and cover the legal side of operations lightly. As with security, we will lightly cover the legal department and stay out of the weeds. There are a handful of areas I'd like to discuss, just to make sure we have this side of operations in order. 

The terms of service, privacy policy, and licensing will affect the business side of API operations. This area governs all other aspects of partner, and 3rd party integrations. These areas need to be well defined, providing clear guidance for developers who are integrating with the APIs being made available.

Branding
As an extension of the legal department, let's also discuss branding for API operations. This is one of the most important of API operations but is often overlooked and under invested in when it comes to execution. Let's talk about a few of the common areas I'm seeing API providers deal with branding.

When it comes to generating value, branding is one of the most important tools in the API toolbox. Extending the network of your retail and online presence, through consistent implementation, execution of the brand is part of the API game. When done right, you can make a significant impact, and extend the reach and strength of a platform using APIs.

Discovery
Any moderately sized company will operate potentially hundreds, if not thousands of APIs, while also depending on tens or even hundreds of external APIs. The discovery of available resources, no matter where they are in the development life cycle is an important area to discuss and plan for.

Much of API discovery will depend on the approach we take to define and design APIs deployed as part of API operations. API discovery is critical to this working, allowing internal, partner, and public consumers to find what they need, and properly integrate into their applications.

Embeddable
Defining where the code meets branding, I'd like to spend some time talking about embeddable tooling available as part of API operations. These are usually JavaScript goodies that leverage the API to help extend the reach of the platform. 

The embeddable portion of operations will help put the branding for the platform into action. Giving developers tools, and other assets that they can put to work in their web and mobile applications, as well as signage, and retail experiences. The goal is to extend the reach of the platform to partner web, mobile, and device properties, with just a simple copy and paste when possible.

Webhooks
It is common to think of APIs as just a one-way street -- allowing consumers to make requests and get responses. A common approach to making APIs a two-way street has emerged called web hooks. Allowing API consumers to define and subscribe to events, making API calls to locations they define, as part of regular API operations.

Webhooks help in alleviating the strain on API resources, reducing the number of calls an application will be making. Allowing applications to define and subscribe to events, and receive webhook notifications occur, such as new product shows up in catalog or a purchase is made.

Orchestration
Let's spend some time discussing the platform orchestration opportunities. Outlining some of the other ways APIs are enabling the synchronization, interoperability, and integration between platforms, and applications used across the enterprise and by partners.  These are the areas I'd like to help you be more aware of when it comes to API enabled orchestration of the platform.

These areas represent how developers and average business users are putting APIs to use as part of regular IT and business operations. By providing API resources to internal and external users, individual users can be empowered to get things done on their own, within the structure of predefined governance and data and content access strategies. Many of these areas are available by default, just by having APIs available--the connectors for moving things around the web with iPaaS, weaving into continuous integration workflows, and spreadsheets are already available out there.

Logging
A structured approach to logging of all API activity is essential to management, security, and the health of operations. It can also become another layer to API operations, as well as monetization, providing access to valuable aggregate, trending, and other valuable data derived from the exhaust of API operations.

This is the layer where we measure everything happening across API operations. It is the awareness of how resources are being accessed and used, provide the data needed to identify where value exists and generate revenue from all aspects operations. While logging should exist at all layers, from the server to client, it should be done sensibly, securely, and with as light of a footprint as possible.

Analytics / Visualization
Providing the meaningful layer on top of platform logging, I want to spend time talking about the analysis, reporting, and visualization requirements around API operations. What is needed to deliver required intelligence to dashboards, dynamic, and static reporting? 

With this layer is developed as part of the overall embeddable API strategy for the platform, all the analysis, and visualizations will be embeddable in emails, other web or mobile applications, delivering insight, awareness, and intelligence wherever it is needed. 

Monetization
Now we are really getting into the business side of this discussion and begin talking about the nuts and bolts of generating revenue from API operations. Before we assemble an actual plan for generating revenue from operations, we need to discuss other aspects of investment in the platform, and how value is generated, or not generated. 

We'll think about monetization from the big picture, but also down to the individual API level--understand what it takes to operate any single API, as well as how they support overall objectives. Without an awareness of what it takes to develop and operate each available API, we will never fully be able to determine the return on investment from any plan we establish.

Plans
With a general awareness of what it will take to develop and operate APIs, we can start planning a little more about how access tiers will be defined, what will be charged for API access, and even what might be paid for incentivizing access to some API resources. I would like to discuss many of the common aspects of how API plans are being operated by the most successful providers like Amazon, Google, and others.

API plans aren't just for public access to APIs, they can be crafted specifically for enterprise level and partner access needs. They can also be established internal consumption, defining the access levels and usage across teams, or geographic locations. API plans aren't just for defining, and charging for API access, they should also be used to measure value created, and possibly defining cash payouts to partners, affiliates, and resellers, encouraging the desired behavior across all API consumers.

Partners
Beyond the basic plans, I wanted to discuss the higher levels of access, providing tiers of access that are usually not metered, or limited, providing special considerations for trusted partners. There are a number of common approaches to helping enable partner integrations, driving the overall objectives of the platform. 

The three main areas of API access companies are thinking about are internal, partner, and the general public. Partner tends to drive a significant portion of the efforts especially early on until providers gain the expertise and platform maturity necessary to successfully operate a fully public API platform. A well-defined partner access can provide the momentum needed to extend the platform's resources to a wider audience in a way that furthers a company mission.

Evangelism / Outreach / Inreach
Last I want to discuss the evangelism, outreach, and what I like to call reach around API operations. Successful API operations have advocates, evangelists, and dedicated resources to helping spread the word about APIs, supporting the needs of consumers, and ensure there is a feedback loop around everything happening. There are some common approaches established by leading providers when it comes to API outreach. 

Outreach is about connecting the feedback loop around API operations. It all starts over again with the feedback gathered at this level. You take this back to the definition layer, enrich your approach, dial in the design of new and existing API efforts, and do it all again. It is touch to articulate and convey the cyclical aspects of API operations, and how companies get better at it with each wave, if they invest in the right areas. API operations are much more than a technical, IT, developer effort--in 2017, it is more about business and people than it ever is about just the data.

Operational Strategy
This is the framework for an API operational strategy. I don't expect you to have all the answers for everything here. It is just meant to help guide our discussion, and provide a framework that we can organize and hang details on for you to take home and consider as part of your team's strategy. Hopefully, this outline provides you with a primer for our discussion. It might seem like a lot, but we should be able to get through in a couple hours, then we can think about the draft of this document for you to take back to your company.