A Framework For Our All Day API Discussion
08 Mar 2017
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.
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:
- What Is API? - Discuss your overall web strategy, and discuss how your API operations will augment, complement, and extend your web presence.
- Why do API? - Cover why APIs will help you deliver to web and mobile, as well as bring more flexibility in any system to system integrations internally, and with your partners.
- API Consumption - Talk about the current and future consumption of 3rd party APIs and from trusted partners, as well as thoughts about internal usage.
- Providing APIs - Talk about the overall world of providing APIs, alongside your existing web and mobile application development.
- The Technology of APIs - Briefly talk about the technological building blocks of providing and consuming APIs, without getting too much into the weeds.
- The Business of APIs - Discuss the nuances of how APIs are being monetized when it comes to retail and products, as well as approaches to data, and other resources.
- The Politics of APIs - Makes sure to highlight many of common legal, privacy, security, transparency, and other political aspects of API operations.
- API Operations - Discuss the final product of our gathering, assembling a strategy for your API operations that can be implemented in phases, and growing with successes.
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.
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.
- Objectives - Get to work defining the primary objectives of your company-wide API operations.
- Web Concepts - Discuss the core elements of the web, and how they are reused for APIs.
- Web Standards - Walk through a handful of the common standards employed as part of API operations.
- Data Schema - Talk about how data is defined, managed, shared, and monetized using APIs.
- API Definitions - Introduce you to common ways in which APIs are being defined and communicated around.
- Access Scopes - Talk through the myriad of ways in which data, content, and other resources are accessed.
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.
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.
- Best Practices - Walk through some of the best practices of API design, and the common approaches.
- Requests / Response - Talk through the common patterns of how API requests are made, and what responses look like.
- Errors - Think briefly about error handling, and how this feeds into overall stability strategy.
- Media Types - Talk about the common media types in play, starting with HTML, and moving into common API patterns.
- Hypermedia - Move into a more detailed discussion around hypermedia, and how it impacts design.
- Schema - Take the building blocks in the definition discussion, and talk about how they'll be applied as part of design.
- Standards - Walk through some of the common standards that will be applied, such as dates, currencies, and other standards.
- Resources - Talk more about the types of resources that will be in play, and what actions can be taken using these resources.
- Process - What does the full process of API design look like, across all APIs being deployed and managed.
- Organization - How are tooling, practices, knowledge, and process stored, shared, and implemented as part of operations.
- Internationalization - What international considerations are there regarding the overall design of the API its design.
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.
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.
- Versioning - How will APIs and their supporting operations be versioned, from design to deprecation?
- Communication - What are the communication considerations around API versioning and changes?
- Hypermedia - Consider hypermedia design practices, and their contribution to the versioning of APIs, and the applications that are integrated.
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.
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.
- Domain(s) - What domains are required for the API, portal, and other supporting elements of operations.
- Management - What is involved with setup and management of the DNS for API operations.
- Stability - How is DNS stability considered, and managed, ensuring resources remain available.
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.
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.
- Platforms - What internal, partner and 3rd party platforms, software, and data solutions are in place, or being considered for the next phase.
- Files - What is a general look at how data and content are accessed in a raw file format, considering spreadsheets, XML, CSV, and many other common formats.
- Process - What is a general look at your overall data acquisition, normalization, development, and production life cycle -- how is data currently flowing inside and outside the firewall.
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.
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:
- Database - Taking the database snapshot, and building on the current data connectivity in place, and drive a sensible web API facade.
- Code - Considering the code required to drive APIs, providing the business logic behind each resource, allowing interaction with data, content, and algorithms.
- Gateway - What are the current gateways are in place, proxying, and providing access to existing systems, starting with databases, but also other systems.
- Cloud - Moving the discussion into the cloud, and talking about what cloud infrastructure is in place, or being considered as part of future API operations.
- On-Premise - How much of the operations are in the cloud vs. on premise? What are the short and long-term strategies for managing API resources?
- Serverless - How decoupled and modular are existing compute resource across the company? Are looking at or discussing a serverless approach to delivering APIs?
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.
- API - Discuss the need for mocking API resources, allowing resources to be designed and tested before costly development begins.
- Data - What needs are there around testing, simulating, and virtualizing data and content across API consumption to support development and production environments.
- Containers - Are there any containerization and virtualization efforts underway, starting with cloud practices, but also focusing on Docker and other leading approaches to isolating deployment.
- Environment - What are the needs for staging, sandbox, as well as production environments? Let's think about a variety of environments beyond just a single production environment.
- Import / Export - What import and export capabilities will be in place to help support the ephemeral nature of virtualized environments, templates, and other enablers of virtualization.
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.
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.
- Overview - What does authentication look like for internal systems and existing applications? Provide some discussion on common concerns, needs, and benefits of the authentication layer of API resources.
- Approaches - Let's walk through some of the common approaches, to making 100% publicly available, all the way to very granular level authorization and access with OAuth--allowing for fine-grained authorization and access at the user and API resource levels.
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.
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.
- Public / Private - Who will be served by a portal? Will there be separate portals for internal, or partner operations? What is the relationship between portals?
- Target Audience - Let's talk about the target audience for portals. Who will be stumbling across them, and who will be regular visitors, making it a community thing.
- Multiple Portals - What are the pros and cons of a single, focused portal vs. a variety of portal serving different audiences, and providing a variety level of security.
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.
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?
- Onboarding - What does onboarding look like for the platform. Once onboard, what happens next? How are users engaged, challenged, and verified?
- Developer Account(s) - What resources are available to developers and consumers to help them manage their account, applications, access, and consumption of resources?
- Internationalization - APIs augment your web presence. What are the international efforts already in place, and what are the considerations for API efforts?
- Corporate - What is the corporate presence within the API operations, and how do management reach across the corporate environment, locations, and brand.
- API - What APIs should be present to help access and manage API operations. Every aspect of API operations should be controlled via APIs, adding another dimension to operations.
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.
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.
- Overview - Let's think through the big picture of getting started for internal and partner users, then discuss any other potential consumers from the media to application developers.
- Steps - What are the steps involved with getting started with integration? What approval steps required? Where can we reduce friction, and encourage new and existing users to do more?
- Targets - Who are we targeting with this process? Are there different steps, and objectives for different users. Are there users who won't actually be building applications, but just encouraging and supporting other consumers?
- FAQ - Let's address some of the questions developers will have with getting started. Let's discuss a way to plug the FAQ into the overall feedback loop, keeping it a growing and evolving list that represents the evolution of API operations.
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.
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.
- Elements - What documentation is required for each available API? Let's talk about common approaches to delivering interactive documentation using API definitions and schema, ensuring there is always up to date documentation available for the entire platform.
- Solutions - Documentation should just be about the API resources available, they should also be about the solutions they provide. Sharing case studies, showcasing applications, and helping consumers understand the opportunities available through integration partnerships.
- Errors - Don't just document what a platform does. Let's talk about what an API platform does when it fails. What are the boundaries, and limitations of a platform, helping consumers develop more resilient applications?
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:
- Overview - What is the overall tone of code for a platform. Is there a heavy lead for development internally, is it partner driven, or will it be more of a community effort? There are plenty of approaches to managing and delivering code in support of API integration.
- Language Samples - Starting with the samples, many providers offer up simple, standalone code samples in a variety of programming languages, giving only what is needed for making and handling of a single request.
- Language SDKs - Additionally more mature providers also offer up complete software development kits that help developers with authentication, as well as working on all available API paths.
- Mobile SDKs - Beyond language SDKs, some API providers focus on mobile SDKs helping consumers deliver iPhone, Android, and Windows applications using API resources.
- Code Management - A discussion about where the code is managed. The common approach is to use Github, which provides the resources for managing code but done in a social way that also allows continued engagement with consumers.
- Platform Development Kits (PDK) - What platform integrations needs will there be? Is there the need or desire to provide WordPress, SalesForce, AWS, Heroku, Facebook, or other existing platform integration.
- Single Page Applications (SPA) - Will there be single page application libraries and scaffolding available for API consumers to use as a start for delivering storefronts, and other deliverables?
- Browser Development Kits (BDK) - What browser add-on toolkits will be needed to help developers better integrate with the browser, providing a different experience for end-users.
- Discovery - How are SDKs discovered, made available, and showcased as part of API operations, making sure standardized, approved resources are put to use as often as possible.
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.
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.
- Overview - What support resources are available? There should be a variety of channels, as well as dedicated human resources to providing timely, and information support when developers need it.
- Self-Service Support - It is common for APIs to provide a variety of self-service support like forums, and knowledge bases, allowing consumers to find answers to their questions 24 hours a day, seven days a week, without directly contacting platform support.
- Direct Support - In addition to a variety of self-service support elements, there should be a handful of direct support channels like email, phone, chat, or a ticketing system.
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.
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.
- Channels - Which channels are used? Blog, Twitter, LinkedIn, Facebook, Instagram, Pinterest, Github, Youtube, and other leading platforms should all be considered for an APIs presence.
- Strategy - I walk you through the common elements of a communication strategy, highlighting what an API can do, what people are doing with the resources, as well as other platform activity, providing a common heartbeat for API operations.
- Process - Let's talk about the execution of the communication strategy. What resources are available, how can it be grown over time, and possibly involve community efforts, encouraging passionate consumers to help communicate the platform message?
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.
- Public - What is involved internally with road map planning, dealing with issues that arise, and the historical tracking of changes--including communication.
- Private - What is involved externally with road map planning, dealing with issues that arise, and the historical tracking of change--including communication.
- Process - What process is involved with change management, and the approval of the roadmap, and establishing of the schedule and timeline.
- Communications - How and when are changes communicated? How transparent is the platform when it comes to issues? How is change communicated?
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.
- Management - How are monitoring and testing set up? What is measured, and how is it reported and communicated across operations.
- Targeted - What does targeted testing and monitoring look like providing regional and international coverage for all testing and monitoring.
- Status - How is the status of operations presented, giving a single external dashboard for consumers to see the current and historical status of operations.
- Notification - Who is notified when there are monitoring, testing, and performance concerns, providing a hierarchy or notifications about changes.
- Reporting - How are results included in internal, and partner reporting, and part of service level agreements and partner contracts for API access.
- 3rd Party - Is there monitoring of third party providers in place, allowing for an understanding of how reliable the 3rd party services being consumed are.
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.
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.
- Assertions - What assertions are made regarding each API resource, as well as groups of API resources. What are the technical details, as well as the plain English explaining the business objective, and the legalese that will pass lawyer review of assertions made?
- Service Level Agreement - What actual service contracts are available and in place regarding API operations. These are the legal contracts that are governing the expectations of API availability and consumption.
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.
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.
- Overview - A well defined, discoverable, and consistent API approach brings a level of security by itself. Let's discuss the other aspects of security when it comes to API operations from authentication outlined above to DNS level attacks that might disrupt operations.
- Transport-Level Security - Encryption by default is the norm for API operations, and we'll discuss encryption in transport, as well as other platform or client, led efforts supporting encryption.
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.
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.
- Privacy - What privacy considerations are there regarding data and content being made available, as well as the developers using the APIs, and the users of the applications that are built on the application.
- Terms of Service - We can talk through some of the ways a platform's terms of service will need to be augmented as part of API operations--discussing any concerns you may have regarding the API terms of service.
- Licensing - I'll walk through the layers of the licensing stack for API operations, starting with server side code, ad extending to the content and data access via API operations, and the client code being put to use across all integrations.
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.
- Overview - Let's talk about goals, and existing branding efforts in place, then we put some thought into what should be in place to not just govern branding but encourage developers to help strengthen the brand and extend the reach.
- Assets - What image assets are in place to help developers understand branding, and easily extend the brand in their applications. Do not make developers work in this area, there need to be a wealth of resources that help them do this right.
- Requirements - Provide a structured set of branding requirements for developers. Let's discuss what some of the common approaches are depending on the implementation.
- Guides - Does it make sense to package up the branding requirements, and assets into a single guide, that developers can share with their team, and bake into their development process.
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.
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.
- Data Inventory - Taking what we discussed in the data and deployment areas of discussion, let's think about these raw sources as part of the wider API discovery discussion.
- Service Inventory - While this is a discussion about the future of APIs, I am guessing there are already a number of existing APIs in place from existing software and infrastructure in place, as well as the consumption of 3rd party Saas and cloud services.
- Schema - How can APIs be discovered using schema, and how can the schema of all data be well defined and reused using common formats like JSON schema.
- Definitions - Along with schema how can API specifications like OpenAPI and APIs.json be applied to help define APIs, and make them more discoverable as part of API operations.
- Search / Catalog - Discovery will involve the presence of a catalog and other solutions for search APIs and schema applied.
- Public API Search Engines / Directories - Is there a need for being listed in public API search engines and directories, helping bring awareness to the existence of API resources.
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.
- Overview - What types of embeddable are there? Let's discuss the simple examples like Twitter and Facebook share buttons, to the more sophisticated commerce, payment, or other API-enabled feature.
- Tools - Let's talk about what tooling is available for defining, customizing, and extending embeddable tooling, helping API consumers build the embeddable toling they need.
- Formats - Building on the API definition portion of this discussion, I want to make sure and discuss some of the open formats for developing embeddable tooling from oEmbed, to common data standards that help streamline the embedding of API tooling.
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.
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.
- Core - Let's talk about what webhooks are, and how they are being put to use my leading API platform. While this isn't a standard, there are common practices in play that can help streamline setup and usage.
- Inbound - Let's talk about allowing for inbound webhooks, defining custom services that can receive requests, based upon specific events, and further define API operations.
- Outbound -- Additionally we will discuss the most common approaches to outbound webhooks that make calls and may push data to external URLs, based upon the occurrence of activities and events across the platform.
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.
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.
- iPaaS - Availability of next generation ETL solutions like If This Then That and Zapier, allow any user to use APIs to orchestrate business processes, defining what APIs means to their regular work.
- Continuous Integration - The evolution of development, making the whole develop stack API driven so that developers can not just access data and content, but they can use APIs to customize their access to resources.
- Spreadsheets - APIs are being used to publish data to spreadsheets, making it available in business functions and reporting, while also making valuable spreadsheet data available for use as part of API deployment and operations.
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.
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.
- Overview - Let's talk about the logging features present with existing infrastructure, and the API management layer of this conversation. Let's talk about the other opportunities involved when logging is API driven, providing programmatic access to every aspect of operations.
- Process - In addition to the recording, and storage of log data let's talk about the analysis and reporting objectives around this data, as well as the privacy and security implications of logging at all layers.
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?
- Analytics - What analysis will be required of data, providing additional algorithmic layers of access beyond just the raw data behind API operations.
- Visualizations - Providing visually derived meaning from all data gathered, and the analysis provided on top of API operations.
- API - Let's makes sure that the analytics layer is all API driven, and the visualization layer is included as part of the embeddable API aspects of operations.
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.
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.
- Acquisition - What is required to acquire data and content, tracking the costs associated with licensing, royalties, or other aspects of discovering and acquiring data or content.
- Development - A breakdown of the costs involved with developing APIs, making data, content, or algorithms available as APIs, and accessible via the platform.
- Operation - Taking a look at what it will cost to operate an API, considering not just the technical, but also the business and legal side of operations.
- Direct Value - Discussing the direct value of data, content, media, and other resources being made available via APIs, exploring the tangible and known value present.
- Indirect Value - Thinking a little about the indirect value generated by APIs, like traffic to website or maybe brand awareness, bringing value to the table, but not direct revenue generation.
- Reporting - What are some of the reporting requirements present around investment into API operations. Understanding and sharing awareness around what it takes to create, and operate an API platform.
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.
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.
- Overview - Let's spend some time discussing how API plans operate. Thinking about the variety of ways APIs can be mixed, matched, and a variety of access levels can be defined to maximize access and usage, while also generating revenue in a sensible way.
- Elements - What are the elements of API access? What other elements are present like support, and specific features are present--further defining what is included beyond just API access.
- Timeframes - What timeframes impact API access plans. What considerations are there per month, day, or possibly by the second? Let's think through the timeframes that drive API plans.
- Metrics - What is being measured as part of each plan level? By the API call, amount of storage, or measuring bandwidth. There are many different metrics to be defined, depending on the resource available, and the monetization objective in play.
- Geo - With cloud computing advances there are many possibilities for additional monetization layers to API plans that include geographically deployed APIs, and in-country services depending on laws and regulatory climate.
- Limits - Let's look to define the limits of each plan, talking about what types of constraints can be put in place to incentivize desired behavior, and drive revenue in an appropriate direction.
- Resources - Let's spend some time thinking about individual API access, and the monetization opportunities involved with different levels of access--this is widely known as service composition, providing different layers of access based upon business objectives.
- Extensions - What opportunities are there for an extension? Can plans be extended and overreached either by usage or possibly paying for preferred treatment--let's think about what the boundaries are.
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.
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.
- Program Details - What existing partner efforts exist? What are the details of existing data or content acquisition or consumption? Beyond the basic levels of access, what should we be thinking about?
- Access Levels - What are the partner level considerations to discuss? Are partners given early or exclusive access to resources? There are many ways to leverage the reading or writing of data and include them as part of partner program incentives.
- Legal - What are the individual legal concerns with partner levels of access. Existing contracts in place, and the existing API-related data or content partnerships that might drive API access tier considerations.
- Marketing Activities - Are there a specific marketing or advertising considerations that might impact partner access, providing special promotions and other activities to drive integration and partnerships.
- Support - What levels of support are given to partner API access levels, and support the overall program. Support is commonly given to the entire community, with an emphasis on preferred or unpaid support for partners.
- Content - What content opportunities are there for partners to participate in. Weaving their messaging into existing marketing and advertising activities, and demonstrate the API integration or application fueling the partnership.
- Communication - What are the additional layers of API operations communication strategy that are focused on partner activity? Some portions of the execution might be dedicated to partners, while others have a general focus.
- Financial - What are the financial reporting, and tracking needs for partner levels of access, measuring their usage of resources, revenue sharing, or collection?
- API - Will there be an API for the partner program? Allowing for programmatic access to program details, activities, support, content, communication, and other elements.
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.
- Goals - Let's start again with the basics. What are our goals in doing APIs, and wanting to take an API-first approach to internal, and partner operations?
- Consumer Outreach - What can be done to reach out to the developer community, and join the existing API community, to drive integration with the platform?
- Partner Outreach - What separate outreach is required for partners, maintaining relationships, and establishing a feedback loop for the future of platform operations?
- Landscape Analysis - What research has been done regarding existing, competitive, or possibly complementary API programs, maybe as part of existing efforts?
- Communications - Let's take the communication strategy and think of it in terms of reaching new users, and spreading awareness of the platform.
- Support - Let's also talk about how support should be woven into outreach strategies, using publicly available platforms that bring SEO exposure for the platform.
- GitHub - When it comes to managing code, and API operations many providers lean on Github for code management, as well as social engagement with the developer community.
- Social Management - Successful API efforts engage with consumers via the social channels they are already operating on, including Github, Facebook, Twitter, and Linkedin.
- Events - What does the event landscape look like for the platform? What conferences, meetups, or hackathons can be attended, or hosted. Is there a calendar available to the community to deepen the engagement with the community.
- Dashboard - Is there a private, or even public dashboard for outreach to begin, providing links to all outreach across operations, all reporting, and community activity?
- Reporting - What regular reporting occurs around outreach, keeping stakeholders informed, and aware--let's discuss how important reporting is to keeping stakeholders invested.
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.
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.