This website is currently dormant!

API Definitions News

These are the news items I've curated in my monitoring of the API space that have some relevance to the API definition conversation and I wanted to include in my research. I'm using all of these links to better understand how the space is defining not just their APIs, but their schema, and other moving parts of their API operations.

The Impact Of Travel On Being The API Evangelist

Travel is an important part of what I do. It is essential to striking up new relationships, and reenforcing old ones. It is important for me to get out of my bubble, expose myself to different perspectives, and see the world in different ways. I am extremely grateful for the ability to travel around the US, and the world the way that I do. I am also extremely aware of the impact that travel has on me being the API Evangelist–the positive, the negative, and the general shift in my tone in storytelling after roaming the world.

One of the most negative impact that traveling has on my world is on my ability to complete blog posts. If you follow my work, when I’m in the right frame of mind, I can produce 5-10 blog posts across the domains I write for, on a daily basis. The words just do not flow in the same way when I am on the road. I’m not in a storyteller frame of mind. At least in the written form. When I travel, I am existing in a more physical and verbal sense as the API Evangelist, something that doesn’t always get translated into words on my blog(s). This is something that is ok for short periods of time, but after extended periods of time on the road, it is something that will begin to take a toll on my overall digital presence.

After the storytelling impact, the next area to suffer when I am on the road, is my actual project work. I find it very difficult to write code, or think at architectural levels while on the road. I can flesh out and move forward smaller aspects of the projects I’m working on, but because of poor Internet, packed schedules, and the logistics of being on the road, my technical mind always suffers. This is something that is also related to the impact on my overall storytelling. Most of the stories I publish on a daily basis evolve out of me moving forward actual projects as part of my API Evangelist work. If I am not actually developing a strategy, designing a specific API, or working on API definitions, discovery, governance, or one of the loftier aspects of my work, the chances I’m telling interesting stories will significantly be diminished.

Once I land back home, one of the first orders of business is to unclog the pipes with a “travel is hard” story. ;-) Pushing my fingers to work again. Testing out the connections between my brain and my fingers. While I also open up my IDE, command line, API universe dashboard, and begin refining my paper notes about what the fuck I was actually doing before I got on that airplane. Make it all work again is tough. Even the simplest of tasks seem difficult, and many of the projects I’m working on just seem too big to even know where to even begin. However, with a little effort, focus, and lack of a plane, train, or meeting to be present for, I’ll find my way forward again, slowly picking back up the momentum I enjoy as the API Evangelist. Researching, coding, telling stories, and pushing forward my projects so that they can have an impact on the space, and continue paying the bills to keep this vessel moving forward in the direction that I want.

API Evangelist API Lifecycle Workshop on API Discovery

I’ve been doing more workshops on the API lifecycle within enterprise groups lately. Allowing me to refine my materials on the ground within enterprise groups, further flesh out the building blocks I recommend to API groups to help them craft their own API strategy. One of the first discussions I start with large enterprise groups is always in the area of API discovery, or commonly asked as, “do you know where all your APIs are?”

EVERY group I’m working with these days is having challenges when it comes to easy discovery across all the digital resources they possess, and put to use on a daily basis. I’m working with a variety of companies, organizations, institutions, and government agencies when it comes to the API discovery of their digital self:

  • Low Hanging Fruit (outline) - Understanding what resources are already on the public websites, and applications, by spidering existing domains looking for data assets that should be delivered as API resources.
  • Discovery (outline) - Actively looking for web services and APIs that exist across an organization, industry, or any other defined landscape. Documenting, aggregating, and evolving what is available about each API, while also publishing back out and making available relevant teams.
  • Communication (outline) - Having a strategy for reaching out to teams and engaging with them around API discovery, helping the remember to register and define their APIs as part of wider strategy.
  • Definitions (outline) - Work to make ensure that all definitions are being aggregated as part of the process so that they can be evolved and moved forward into design, development and production–investing in all of the artifacts that will be needed down the road.
  • Dependencies (outline) - Defining any dependencies that are in play, and will play a role in operations. Auditing the stack behind any service as it is being discovered and documented as part of the overall effort.
  • Support (outline) - Ensure that all teams have support when it comes to questions about web service and API discovery, helping them initially, as well as along the way, making sure all their APIs are accounted for, and indexed as part of discovery efforts.

API discovery will positively or negatively impact the rest of the API lifecycle at any organization. Not knowing where all of your resources are, and not having them properly defined for discovery at critical design, development, production, and integration movements, is an illness all companies are suffering from in 2018. We’ve deployed layers of services to deliver on enterprise growth, and put down a layer of web APIs to service the web, mobile, and increasingly device-based applications we’ve been delivering. Resulting in a tangled web of services, we need to tame before we can move forward properly.

Let me know if you need help with API discovery where you work. It is the fastest growing aspect of my API workshop portfolio. Aside from security, I feel like API discovery is the biggest challenge facing large enterprise groups learning to be more agile, flexible, and pushing forward with a microservices, and event-driven way of doing business. I definitely don’t have all the solutions when it comes to API discovery, but I knew have a lot of experience to share around how we are defining our enterprise capabilities and resources, and making them more discoverable across our entire API catalog.

API Evangelist API Lifecycle Workshop on API Design

I’ve been doing more workshops on the API lifecycle within enterprise groups lately. Allowing me to refine my materials on the ground within enterprise groups, further flesh out the building blocks I recommend to API groups to help them craft their own API strategy. One area of the API lifecycle I find more groups working on these days, centers around a design-first approach to the API lifecycle.

While not many groups I work with achieved a design-first approach doing APIs, almost all of them I talk to express interest in making this a reality at least within some groups, or projects. The appeal of being able to define, design, mock, and iterate upon an API contract before code gets written is very appealing to enterprise API groups, and I’m looking to help them think through this part of their API lifecycle, and work towards making API design first a reality at their organization.

  • Definition (outline) - Using definitions as the center of the API design process, developing an OpenAPI contract for moving things through the design phase, iterating, evolving, and making sure the definitions drive the business goals behind each service.
  • Design (outline) - Considering the overall approach to design for all APIs, executing upon design patterns that are in use to consistently deliver services across teams. Leveraging a common set of patterns that can be used across services, beginning with REST, but also evetually allowing the leveraging of hypermedia, GraphQL, and other patterns when it comes to the deliver of services.
  • Versioning (outline) - Managing the definition of each API contract being defined as part of the API design stop for this area of the lifecycle, and having a coherent approach to laying out next steps.
  • Virtualization (outline) - Providing mocked, sandbox, and virtualized instances of APIs and other data for understanding what an API does, helping provide an instance of an API that reflects exactly how it should behave in a production environment.
  • Testing (outline) - Going beyond just testing, and making sure that a service is being tested at a granular level, using schema for validation, and making sure each service is doing exactly what it should, and nothing more.
  • Landing Page (outline) - Making sure that each individual service being designed has a landing page for acccessing it’s documentation, and other elements during the design phase.
  • Documentation (outline) - Ensuring that there is always comprehensive, up to date, and if possible interactive API documentation available for all APIs being designed, allowing all stakeholders to easily understand what an API is going to accomplish.
  • Support (outline) - Ensuring there is support channels available for an API, and stakeholders know who to contact when providing feedback and answering questions in real, or near real time, pushing forward the design process.
  • Communication (outline) - Making sure there is a communication strategy for moving an API through the design phase, and making sure stakeholders are engaged as part of the process, with regular updates about what is happening.
  • Road Map (outline) - Providing a list of what is being worked on with each service being designed, and pushed forward, providing a common list for everyone involved to work from.
  • Discovery (outline) - Make sure all APIs are discoverable after they go through the design phase, ensuring each type of API definition is up to date, and catalogs are updated as part of the process.

I currently move my own APIs forward in this way using a variety of open source tooling, and GitHub. I’m working with some groups to do this in, as well as Postman. I don’t think there is any “right way” to go API define and design first. I’m here to just educate teams about what is going on out there. What some of the services and tools that help enable an API design first reality, and talk through the technological, business, and political challenges are preventing a team, or entire enterprise group from becoming API design first.

Let me know if you need help thinking through the API design strategy where you work. I’ve been studying this area since it emerged as a discipline in 2012, led by API service providers like Apiary, but continue with other next generation platforms like, APIMATIC, and others. For me, API design is less about REST vs Hypermedia vs GraphQL, and more about the lifecycle, services, tooling, and API definitions you use. I’m happy to share my view of the API design landscape with your group, just let me know how I can help.

API Developer Outreach Research For The Department of Veterans Affairs

This is a write-up for research I conducted with my partner Skylight Digital. The team conducted a series of interviews with leading public and private sector API platforms regarding how they approached developer outreach, and then I wrote it up as a formal report, which the Skylight Digital team then edited and polished. We are looking to provide as much information as possible regarding how the VA, and other federal agencies should consider crafting their API outreach efforts.

This is Skylight’s report for the U.S. Department of Veterans Affairs (VA) microconsulting project, “Developer Outreach.” The VA undertook this project in order to better understand how private- and public-sector organizations approach Application Programming Interface (API) developer outreach.

In preparing this report, we drew on nearly a decade’s worth of our own API developer outreach expertise, as well as information obtained through interviews with seven different organizations. For each interview, we followed an interview script (see Appendix A) and took notes. The Centers for Medicare & Medicaid Services (CMS) Blue Button API program (see Appendix B), the Census Bureau (see Appendix C), the OpenFEC program (see Appendix D), and Salesforce (see Appendix E) all agreed to releasing our notes publicly. The other three organizations (a large social networking site, a government digital services delivery group, and a cloud communications platform) preferred to keep them private.

We structured this report to largely reflect the interview conversations that we held with people who are involved in developer outreach programs and activities. These conversations focused around the following questions:

  1. What is the purpose and scope of your API developer outreach program?

  2. What does success look like for you?

  3. What are the key elements or practices (e.g, documentation, demos, webinars, conferences, blog posts) that you are using to drive and sustain effective adoption of your API(s)?

  4. Do you make use of an API developer sandbox to drive and sustain adoption? If so, please describe how you’ve designed that environment to be useful and usable to developers.

  5. What types of metrics do you use to measure adoption effectiveness and to inform future decisions about how you evolve your program?

  6. How is your outreach program structured and staffed? How did it start out and evolve over time?

  7. Imagine that you are charged with ensuring the complete failure of an API developer outreach program. What things would you do to ensure that failure?

  8. What big ideas do you have for evolving your outreach program to make it even more effective?

if we were forced to distill all of the interviews and all of our existing information down to a single essential piece of advice, it would be this: involve the programmers who are going to be using your APIs. By “involve,” we mean:

  1. Engage them early.

  2. Support the users with documentation, hackathons, forums, and other types of engagement activities.

  3. Measure the happiness of the programmers who are using your APIs, as well as the number of times that they use them and how they use them.

  4. Prioritize your APIs so as to maximize the utility to would-be programmers.

In the pages below, you will find a large number of specific suggestions culled from extensive interviews and our collective personal experience. All of these specific techniques are in service to the idea of designing the API program with the programmers who will use the API in mind at all times.

Research findings and thoughts

Purpose and scope of developer outreach programs

What we learned

Different API programs have different purposes, and these purposes are fulfilled by varying levels of API outreach resources. Just as organizations have invested differing amounts of resources into their web presence over the last 25 years, the API providers we talked to are each at different stages in their API journey. This variety presented us with a range of informative stories concerning outreach programs.

The purpose behind APIs

Our interviews revealed a number of potential purposes for API development, a number of which are presented below:

  • Build it and they will come: It is common for companies, organizations, institutions, and government agencies to launch an API effort with no specifically-stated purpose. They make resources available, build awareness amongst developers, and encourage innovation. While such organizations may not know what the future will hold, they believe that their investment in their API platform in a sensible and pragmatic way will attract developers and the inevitably innovative applications they will bring.

  • A focus on APIs as a product: Some interviewees we spoke to are fully invested in their API efforts, treating their APIs as a product in and of themselves. They develop formal programs around their API operations, treat API consumers as end customers, and consistently ensure their programs have the resources they need. In short, they treat API operations like a business and run them as efficiently as possible, even if commercial sales is not the end goal.

  • A focus on APIs as an enabler: Other interviewees we consulted focus on ensuring the availability of APIs as a means to support an existing web or mobile application; in a sense, the API is relegated to a secondary role relative to the primary application’s existence. APIs for these kinds of organizations serve to drive traffic, adoption, and integration when it comes to a larger vision, but the APIs themselves are simply enablers for the overall platform.

  • A focus on the developer: Beyond the API as a product — and the web and mobile apps they power — API efforts tend to focus on the developer. Development-focused APIs emphasize what developers will bring to the table when they have the resources and support they need, and are thus central to the investment and engagement necessary for successful outreach/development.

  • Attract unique entities: API platforms are often aimed at attracting the attention of interesting/progressive companies, universities, institutions, and other entities. These external entities can often put API resources to use in new and innovative ways, and in doing so, they can bring attention and potential partnerships to the platform.

  • Leverage the network effect: Some API providers we interviewed expressed an interest in joining a wider network of collaborative open data and API efforts. They felt that working in concert with others, by bringing together many different federal, state, or municipal agencies, would benefit the platforms. Further, they felt this would allow the API initiatives to be led by either policy or private interests.

  • Save developers time: Overall, the most positive motivation for API development expressed by existing providers was to streamline API onboarding and integration. Further development would help internal, partner, and 3rd party public developers be more successful in putting API resources to work in their web, mobile, and device applications.

The scope of API investment

The programs we spoke to each had differing levels of investment, access to resources, and primary purposes. Since the scope of an API investment is naturally a function of these factors, this meant that the organizations we interviewed had different intended scopes for their API projects. We have collated a selection of these scopes below.

  • Starting small: A common theme across API operations we spoke with was the importance of starting small and building a stable foundation before attempting larger infrastructure development. Beginning with a basic, yet valuable set of API resources, fleshing out the entire lifecycle, and processing around what is necessary to be successful before scaling and increasing the scope of API operations was routinely described as a critical part of any API scope.

  • Invest as it makes sense: A lack of resources is a common element of slow growth and unrealized API operations. Bringing significant levels of investment to projects while simultaneously applying appropriate human and technological capital to API operations were universally mentioned by our interviewees as critical to seeing desired results.

  • Working with what you have: Almost all the API programs we spoke to worked in resource-starved environments. They wished to do more and to be more, but lacked the time, human investment, and technical resources to make it happen. This forced the organizations to work with what they had, making the most of their limited opportunities while hoping for eventual greater contributions.

  • A focus on improvement: All the API programs we interviewed expressed that they wanted to be doing more with their programs. They want to formalize their approach and increase their resource and labor investment in the areas in which they have seen success. Ultimately, their target scope was to focus not on just meeting expectations, but on moving towards excellence and mastery of what it takes to scale their API efforts.

Every API effort clearly has its own personality, and while there are common patterns, the environment, team, and amount of resources available appears to dictate much of the scope of developer outreach programs. However, the scope of any effort will always start small and move forward incrementally as confidence grows.

What our thoughts are

We learned a lot talking to API providers about the purpose and scope of their API operations. Our interviews also reinforced much of what we know about the API operations of leading providers like Amazon and Google. When it comes to the motivations for developing APIs, ensuring an appropriate level of investment and planning for future scalable growth are necessary steps in giving an API the best chance to succeed.

Augmenting what we learned from providers, we recommend focusing on the following areas in order to achieve API purposes, grow and scale API operations, and integrate API technology into the fabric of an organization’s overall operations.

  • APIs are a journey: Always view API operations as a journey and not a destination, setting expectations appropriately from the beginning. Do not raise the bar too high when it comes to achieving goals, reaching metrics, and getting the job done. API operations will always be an ongoing effort, with both wins and losses along the way.

  • Always start small: Reiterating what we researched in the API sector as well as what we confirmed in our interviews, it is important to build a small, stable base before moving forward. This does not mean you cannot develop rapidly, but before you do, make sure you’ve researched the API and planned for its success, understanding what will be needed throughout the lifecycle of all APIs you intend to deliver.

  • Center on the end user: It is always important that every goal and purpose you set for your API platform center on its end-users. While the platform and developer ecosystem is always a consideration, the end-user is the central focus of the “why” and the “how” for API technologies, especially consider the scope of operating an API in both the private and the public sector.

  • A dedicated team: Even if it is a small group, always work to dedicate a team to API operations. While APIs will ultimately be an organization-wide effort, it will take a dedicated team to truly lead the API to success. Without centralized, dedicated leadership, APIs will never attain true relevance within an organization, leaving to be a side project that rarely delivers as expected.

  • Everyone pitches in: While a dedicated team is a requirement, an API’s development should always invite individuals from across an organization to join in the process. Ideally, API operations are a group effort led by a central team. It is important to encourage individual API teams to feel a sense of ownership over their API, just as it is important to encourage business users to participate in development conversations.

  • Striving for excellence: API operations will always be forced to deal with a lack of resources. That is simply a fact of dealing in APIs. However, each API program should be seeking excellence, working to understand what is needed to move APIs forward in a healthy way. Improving upon what has already been done, refining processes that are in motion, and making sure all APIs are iteratively improved continually benefits a platform’s end users.

  • Continued investment: Always be regularly investing in the API platform. Continued input of both human resources and financial resources helps to ensure that a platform is not starved along the way. Otherwise the API-in-question will constantly fall short and threaten the viability of the platform in the long term.

While the purpose of an API may depend on the mission of its developing organization, in the end, APIs always exist to serve end-users while protecting the interest of a platform. The scope of any such API will depend on the commitment of an organization, and as such, there is no “right answer” to the question of determining the purpose of any single API platform. The only true constraint is the assurance that the API remains in alignment with an organization’s mission as it grows and scales.

How success is defined

With a variety of possible purposes, scopes, and approaches, an API’s success can be defined in a myriad of ways. Depending on the motivations behind the API, and the investment made, the measure of success will depend on what matters to the organization. However, there are some common patterns to defining success, which we extracted from both the interviews we conducted and the research we performed as part of this outreach study.

What we learned

Along with what we learned about the purpose and scope of API platforms, we discovered more about the different ways in which API providers are defining success. We have collected the highlights among these metrics below.

  • Building awareness: API success revolves around building awareness that an API exists, as well as awareness of the value of the API resources that are being made available. Awareness is not simply a consumer side consideration, though; providers, too, must possess an awareness of the value of their resources in relation to both other API developers and consumers alike.

  • Attracting new users: Bringing attention to an API and attracting new users is one of the most common ways of measuring the success of API operations. While new users won’t always immediately become active users, their interest and involvement will bring attention to and awareness of what the API platform can deliver. Attracting new users is one of the easiest and most accessible ways to measure the success of any API, according to our interviews, but importantly, none of the platform providers we spoke to recommended that an organization should stop there.

  • Incentivizing active users: While attracting new users is easy, producing active users is much harder. The easier it is to onboard with an API and make the first series of API calls, the greater the likelihood that API consumers will integrate the platform into their own resources and work, which is a critical metric for any API provider.

  • Applications: Applications and development are the cornerstones that incentivize API providers to invest in APIs, and across the board, our interviewees cited application integration and involvement as a prime candidate for determining an API’s success. This could be quantified both in terms of new applications relying on the API platform, as well as active application processes that integrate with the API’s platform. In either case, measuring usage was considered an excellent means to justify the existence and growth of an API platform.

  • Entities: Getting the attention of companies, organizations, institutions, and other government agencies is an important part of the the API journey. In particular, developing an awareness of and encouraging the usage and adoption of APIs among groups already leveraging the technology is an important metric by which success can be determined.

  • End users: Of course, API providers articulated the importance of serving end-users. Besides serving an organization’s mission, the true purpose of an API is to satisfy an end-user, and so measuring success based upon how much value is created and delivered to these users and customers, and even the public at large, can directly verify that an API is living up to its billing.

  • Stakeholders: Further discussions with API providers implied that success is also defined in terms of involvement with other stakeholders. Ensuring that the definition of success was crafted in an inclusive way allows everyone involved and impacted by the project to input their voice. This widens the target audience to make sure success is a large umbrella that covers as many individuals within an organization as possible.

  • New resources: An additional area that was used to define success was the number of new API resources added to a platform. If an organization is currently in the development phase and deploying APIs into production, it is likely that a platform already has a handle on what it takes to successfully deliver APIs throughout their lifecycle. Making new APIs a great way to understand the velocity of any platform, and how well it is ultimately doing.

Measuring the success of an API platform is a much more ambiguous goal than determining scope, purpose, and investment. Our interviews revealed that success often means different things to different providers. Moreover, an organization’s understanding of success is also something that will evolve over time. We learned a lot from API providers about pragmatic views on what API success looks like, and now we would like to translate that into some basic guidance on how to help ensure the success of providing APIs.

What our thoughts are

Defining, measuring, and quantifying the success of API operations is not easy. As discussed above, measuring success functionally amounts to hitting a moving target. It is important to start with the basics, be realistic, and define success in a meaningful way. Adding to what has been gathered from interviews with API providers, we recommend a consideration of the following factors when it comes to defining just exactly what success is.

  • Know your resources: Understand the resources you are making available via an API. Ensure that they are well defined and made accessible in ways that consider security, privacy, and the interests of all stakeholders. Do not just open up APIs for the sake of delivering APIs — make sure the resources are well defined, designed, and serve a purpose.

  • Manage your APIs: API management is essential to measuring success. It is extremely difficult to define success without requiring all developers to authenticate, log, quantify, and analyze their consumption. Measuring these kinds of consumption activities helps to quantify the value produced by the API and its related platform, and an understanding of this value serves as the foundation for any API’s future success.

  • Have a plan: There is no success without a plan. A set of plans are required to apply at the management level in order to quantify the addition of new accounts, define whether they are active or not, and understand how applications are putting resources to work. Providing a plan for how resources are made available, and how they are consumed, generates a framework to think about and measure what API success means.

  • Measure portal activity: Treat your API developer portals as you would any other web property and actively measure its traffic. Apply data-analytic solutions to track sessions, time, and visitors, and use this information to contribute to a sales and marketing funnel that can be used to understand how developers are using portal resources. Importantly, this kind of analysis can also discover points of friction that developers may be encountering when trying to use your API platform.

  • Analyze and report: Produce weekly, monthly, quarterly, and annual reports from data gathered across the API stack, API portal, and from social media. Developing an understanding of what is happening based upon actual data, and consistently reporting upon findings with all stakeholders in API operations, ensures both transparency of API knowledge and information access to formulate plans for growth.

  • Discuss and evangelize: Have a strategy for taking any analysis or reporting from API operations and disseminating it amongst stakeholders. With these resources distributed, consider conducting regular on- and off-line discussions around what they mean. Work with everyone involved to understand the activity across a platform, and use these discussions to transform the understanding of success as platform awareness grows.

  • Make things observable: Make every building block of API operations observable. Ensure that everything has well defined inputs and outputs, and consider how these can be used to better understand whether the platform is working or not. Allowing every single aspect of the platform to be able to contribute to an overall definition of what success means by providing real-time and historic data around how resources are being used can signal important insights about an API and how it might be improved.

The success of an API platform will mean different things to different groups and will evolve over time as awareness around an organization’s resources grows. Know your resources, properly manage your APIs, and have a plan, but make sure you are constantly reassessing exactly what success means while having ongoing conversations with stakeholders. With more experience, you will find that API platform success becomes much more nuanced, but importantly, it also becomes easier to define once you know what it is that you want.

Key practices for driving and sustaining adoption of APIs

After a decade of leading tech companies operating API programs, and a little over five years of government agencies following their lead, a number of common practices emerged that helped drive the adoption of APIs and support relationships between provider and consumer. We spent some time talking to API providers about their approaches, while also bringing our existing research and experience to the table, and have collected our responses and analysis below.

What we learned

This is one area where we believe that our existing research outweighed what we learned in talking to API providers, but the conversations did reinforce what we know while also illuminating some new ways to look at operational components. Here are the key practices our interviewees provided for driving and sustaining the adoption of APIs.

  • Documentation: Documentation is the single most important element that needs to accompany an API that is being made available. This transforms the process of learning about what an API can do from static to interactive (such as by using OpenAPI specifications) and renders the API a hands-on experience.

  • Code: Providing samples, SDKs, start solutions, and other code elements is vital to making sure developers understand through demonstration how to integrate with APIs in a variety of programming languages.

  • Content: Content is critical. Invest in blog posts, samples, tutorials, case studies, and anything else you think will assist your consumers in their journey. We heard over and over how important a regular stream of content is for attracting new developers, keeping active ones engaged, and putting API resources to work.

  • Forums: Provide a forum where developers can find existing answers to their questions while also being able to ask new questions. Offering a safe, up to date, well moderated place to engage in asynchronous conversations around an API platform ensures that dialogue is always happening, which means that use and progress are in continued development.

  • Conferences: Conducting workshops and attending relevant conferences where potential API consumers will be is an important practice in furthering the outreach of an API platform. Engage with your community — both consumers and developers — instead of just pushing content to them online.

  • Proactive: Make sure you are proactive in operating your API platform by constantly marketing your work to developers (remember, continually attracting new attention is vital). At the same time, work to provide existing developers with what they will need based upon common practices across the API sector. Investing in developers by giving them resources they will need before they have to ask for it makes an API’s community feel alive and healthy.

  • Reactive: While proactivity is important, an API team must also be able to react to any questions, feedback, and concerns submitted by API consumers and other stakeholders. Ensuring people do not have to wait very long for an answer to their question makes consumers, developers, and stakeholders alike feel like they are considered a relevant and important part of the API community.

  • Feedback loops: Having feedback loops in place are essential to driving and sustaining the adoption of APIs. Without one or more channels for consumers to provide feedback, as well as responsive and attentive API providers who analyze how the feedback can fit into the overall API plan, API operations will never quite rise to the occasion.

  • Management: Almost all API providers we talked to articulated that having a proper strategy for API management, as well as an investment in services and tooling, was essential to onboarding new consumers. Additionally, this kind of investment facilitates an understanding of how to engage with and incentivize the usage of API resources by existing users. Without the ability to authenticate, define access tiers, quantify application usage, log all activity, and report upon usage and activity across dimensions, it is extremely difficult to scale platform adoption.

  • Webinars: For an enterprise audience, webinars were a viable way to educate new users about what an API platform offers, as well as helping to bring existing API consumers up to speed on new features. Not all communities are well-suited for webinar attendance, but for those that are, it is a valuable tool in the API toolbox.

  • Tutorials: Providing detailed tutorials on how to use an API, understand business logic, and take better advantage of platform resources were all common elements of existing API provider options. Breaking down the features of the platform and providing simple walkthroughs that help consumers put those features to work can streamline the integration and onboarding process that users face when working with APIs.

  • Domain: Our interviewees mentioned that having a dedicated domain or subdomain for an API developer portal significantly helped in attracting new users by providing a known location for existing developers to find the resources they are looking for.

  • Explorer: In some cases, it is important to provide a more hands-on, visual way to explore resources available within an API rather than simply listing or describing such features in documentation. For new and particularly inexperienced users of API technologies, resources that can “connect the dots” between the API’s functional support and the actual implemented pathway of using a particular API tool can be immeasurably important in user retention.

We learned that many API providers in the public sector are actively learning from API providers in the private sector. They employ many of the same elements used by leading API providers who have been doing it for a while now. However, we also found evidence of innovation by some of the public sector API providers we interviewed, especially in the realm of onboarding and retaining new users.

What our thoughts are

Below, we have constructed a list of common building blocks that should be considered when developing, operating, and evolving any API platform. These recommendations are the results of formalizing what we learned as part of the interview process, as well as leveraging eight years worth of research. Our objective is to give API providers the elements they need to attract and engage with new users, while also pushing existing users to be more active. We have broken down our recommendations into eleven separate areas, which are further discussed below.


It is important to provide a single known location where API providers and consumers can work together to integrate the offered resources into a variety of web, mobile, device, and network applications, as well as directly into other systems. Several components play into the successful adoption and consumption of APIs published to a single portal.

  • Overview: A simple overview explaining what a platform does and clearly defining the value the API offers to consumers.

  • Getting started: A simple series of steps that help onboard a new user so that they can begin putting API resources to work.

  • Documentation: Interactive documentation for all APIs and schema (preferably created in OpenAPI or another interactive API specification format).

  • Errors: A simple, clear list of all the possible errors an API consumer will encounter, starting with HTTP status codes and then proceeding to any specialized schema used to articulate when API errors occur.

  • Explorer: A visual representation of the resources available within the API that allows consumers to search, browse, and explore all available resources without needing to know or write code. Note: it is always helpful to provide a direct link to replicate a search using the API.

These elements set the foundation for any API operations, providing the basic elements that will be needed to onboard with an API. They establish an interface for the other features that will be needed to incentivize deep and sustaining integrations with any platform.


Besides the basic functionality described above, industries have turned toward a suite of machine-readable definitions to drive API integrations. Due to the ubiquity of a number of these definitions, we have collected a handful of specification formats that we recommend making a part of the base of any API operations.

  • OpenAPI: An interactive documentation standard that describes the functionality of an API in a machine-readable way.

  • Postman: A standard collection that provides a transactional, runtime-oriented definition of the feature interface of an API for use in client tooling.

  • JSON Schema: A widely used specification that describes the objects, parameters, and other structural elements of the consumption of API resources.

  • APIs.json: A discovery document that provides a machine-readable index of API operations with references to the portal, documentation, OpenAPI, Postman, and other building blocks of an API platform.


It is common practice for API providers to invest in a variety of code-focused resources to help jumpstart the onboarding process for API developers. This reduces the number of technical steps necessary for the technology to successfully integrate with other platforms. Here are the building blocks we recommend considering when crafting the code portion of any developer outreach strategy.

  • Github/Gitlab: Use a social coding platform to manage many of the technical components used to support API developers.

  • Samples: Publish simple examples of making individual API calls in a variety of programming languages.

  • SDKs: Provide more comprehensive software development kits in a variety of programming languages for developers to use when integrating with API resources.

  • PDKs: Provide platform development kits that help developers integrate with existing solutions they may already be using as part of their operations.

  • MDKs: Provide mobile development kits that help jumpstart the development of mobile applications that take advantage of a platform APIs.

  • Starters: Publish complete applications that provide starter kits that developers can use to jumpstart their API integrations.

  • Embeddables: Provide buttons, badges, widgets, and bookmarklets for any API consumer to use when quickly integrating with API resources.

  • Spreadsheets: Offer spreadsheet connectors that allow API consumers to use platform APIs within Microsoft Excel and Google Sheets.

  • Integrations: Invest in a suite of existing integrations with other platforms that API consumers can take advantage of, providing low-code or no-code solutions for integrating with APIs.

While we have presented a variety of code-related resources, we want to point out the caveat that these tools should only be employed if an organization possesses the resources to properly maintain and support them. These elements can provide some extremely valuable coding solutions for developers and consumers to put to work, but if not properly done, they can also quickly become a liability, driving developers away.


In addition to simpler request-and-response delivery and documentation methods, we also recommend thinking about the following event-driven possibilities, which can also be used to incentivize deeper engagement and workflow with an API.

  • Webhooks: These can provide ping and data push opportunities, which allow API consumers to be notified when any event occurs across an API platform.

  • Streams: Providing high-level or individual streams of data allow for long-running HTTP or TCP connections with API resources.

  • Event types: In many cases, it is helpful to publish a list of the types of possible API events, as well as opportunities for subscribing to webhook or streaming channels.

  • Topics: Similarly, developers and consumers alike may find a published list of platform-related topics useful, particularly one that allows API consumers to search, browse, and discovery exactly the topical channels they are interested in.

These event-based tools help augment existing APIs and make them more usable by API consumers at scale. They facilitate a meaningful application experience for end-users, allowing them to stay tuned to specific topics. This in turn fine-tunes the experience for developers,which further drives adoption, ultimately establishing more loyal consumers at the API integration and application user levels.


One of the cornerstones for defining, quantifying, and delivering successful API onboarding and engagement is API management. The following list contains some core elements of API management that should be considered as any API provider is planning, executing, and evolving their operational strategy.

  • Authentication: Providing clear options for onboarding using Basic Auth, API Keys, JWT, or OAuth keeps things standardized, well-explained, and frictionless to implement.

  • Plans/tiers: Establishing well-defined tiers of API consumers in terms of how they access all available API resources can inform the provision of structured plans that define how an API’s resources are being utilized.

  • Applications: Individual applications should be at the center of consumer API engagement. In particular, applications that help onboard new users so that they can begin consuming API resources are imperative.

  • Usage reporting: Tools and metrics that provide real-time and historical data, as well as access to multi-dimensional reporting across all API consumers is useful in analyzing the API’s usage and performance. This information can be helpful to developers in defining the stage of their API journey, as well as any additional resources they might wish to consider.

There are many other aspects of API management, but these building blocks reflect the consumer-facing elements that help onboard new users and drive increased engagement with existing consumers. API management is an area in which API providers should not be reinventing proven methods that already work: the best practices established over the last decade by leading API providers already account for strong engagement and retention levels for users and service providers.


Engagement is important for consumers not only with the tools of the API, but the communications and news surrounding the API. Streams of information across multiple channels can help unite a communications strategy for any API platform. We have collected the best examples of such information feeds below.

  • Blog: An active blog with an Atom feed, one for each individual API and/or overall platform.

  • Twitter: A dedicated Twitter account for the entire API platform, providing updates and support.

  • GitHub: A GitHub organization dedicated to the platform, with accounts for each API team member. The organization leverages the platform for content as well as code management.

  • Reddit: A helpful forum for answering questions, sharing content, and engaging with consumers on the social bookmarking platform.

  • Hacker News: Another helpful discussion board for answering questions, sharing content, and engaging with consumers.

  • LinkedIn: A business social network enterprise devoted to engaging with consumers. An established LinkedIn page for the platform can be useful for regularly publishing content, as well as engaging in conversations via the platform.

  • Facebook: Similar to LinkedIn, a Facebook page for the platform is helpful in engaging with API consumers via their social media presence. It can be used to regularly publishing content and engage in network-broadcast conversations via social platforms.

  • Press: A platform section detailing the latest releases, as well as a feed that users can subscribe to in order to receive a regular stream of news on the platform.

A coherent communication, content, and social media strategy will be the number one driver of new users to the platform while also keeping existing developers engaged. These communication building blocks provide a regular stream of information and signals that API consumers can use to stay informed and engaged while putting API resources to use in their applications.

Direct support

Besides communication, direct support channels are essential to completing the feedback loop for the platform. There are a handful of common channels API providers use to provide direct support to API consumers, allowing them to receive support from platform operations. We recommend the following selections.

  • Email: Establish a single, shared email address for the platform in which all platform support team can provide assistance.

  • Twitter: Provide support via Twitter, pushing it beyond just a communication channel and making it so that API consumers can directly interact with the platform team.

  • GitHub: Do not just use GitHub for code or content management: leverage individual team member accounts to actively support using GitHub issues, wikis, and other channels the social coding platform provides.

  • Office hours: Provide regular office hours where API consumers can join a hangout or other virtual group chat application in order to have their questions answered.

  • Webinars: Provide regular webinars around platform specific topics, allowing API consumers to engage with team members via a virtual platform that can be recorded and used for in-direct, more asynchronous support in addition to live feedback.

  • Paid: Provide an avenue for API consumers to pay for premium support and receive prioritization when it comes to having their questions answered.

With a small team, it can be difficult to scale direct support channels properly. It makes sense to activate and support only the channels you know you can handle until there are more resources available to expand to new areas. Ensuring that all direct support channels are reactive in terms of communication will help deliver value by bringing the feedback loop back full circle.

Indirect support

After direct support options, there should always be indirect/self-support options available to help answer API consumers’ questions. Such options allow users to get support on their own while still leveraging the community effect that exists on a platform. There are a handful of proven indirect support channels that work well for public as well as private API programs.

  • Forums: Provide a localized, SaaS, or wider community forum for API consumers to have their questions answered by the platform or by other users within the ecosystem.

  • FAQ: Publish a list of common questions broken down by category, allowing API consumers to quickly find the most common questions that get asked. Regularly update the FAQ listing based on questions gathered using the platform feedback loop(s).

  • Stack Overflow: Leverage the question and answer site Stack Overflow to respond to inquiries and allow API consumers to publish their questions, as well as answers to questions posed by other members of the community network.

Indirect, self-service support will be essential to scaling API operations and allowing the API team to do more with less. Outsourcing, automating, and standardizing how support is offered through the platform can make API support available 24 hours per day, turning it into an always-available option for motivated developers to find the answers they are looking for.


Beyond the documentation and communication, it is helpful to provide other resources to assist API consumers in onboarding and to strengthen their understanding of what is offered via the platform. There are a handful of common resources API providers make available to their consumers, helping to bring attention to the platform and drive usage and adoption of APIs.

  • Guides: Providing step by step guides covering the entire platform, or individual sections of the platform, helps consumers understand how to use the API to solve common challenges they face.

  • Case studies: Examples such as real-world case studies of how companies, organizations, institutions, and other government agencies have put APIs to work in their web, mobile, device, and network applications can help demonstrate the variety of functions that an API platform can perform.

  • Videos: Make video content available on YouTube, and other platforms. Providing video walkthroughs of how the APIs work and the best way to integrate features into existing applications can demystify the process of onboarding with API technologies.

  • Webinars: While webinars can be a helpful source of information to API consumers trying to understand specific concepts, maintaining and publishing an archive of webinars can serve as a historic catalog of such searches, which can provide targeted Q&A for how to put API platforms to work.

  • Presentations: Provide access to all the presentations that have been used in talks about the platform, allowing consumers to search, browse, and learn from presentations that have been given at past conferences, meetups, and other gatherings.

  • Training: It can be immensely helpful to invest in formal curriculum and training materials to help educate API consumers about what the platform does. This provides a structured approach to learn more about the APIs and gives developers access to comprehensive training materials users can tap into on their own schedule.

Like other areas of this recommendation, these resource areas should only be invested in if an organization has the resources available to develop, deliver, and maintain them over time. Providing additional resources like guides, case studies, presentations, and other materials help further extend the reach of the API platform, allowing the API team behind operations do more with less, as well as reach more consumers with well constructed, self-service resources that are easy to discover.


One important attribute of API platforms that successfully balance attracting new users and creating long term relationships is platform observability. Being able to understand the overall health, availability, and reliability of an API platform allows API consumers to stay informed regarding the services they are incorporating into their applications. There are several key areas that contribute to the observability of an API platform.

  • Roadmap: A simple list of what is being planned for the future of a platform, one that provides as much detail and ranges as far into the future as possible.

  • Issues: A document of any open issues that exist, allowing API consumers to quickly understand if there are any open issues that might impact their applications.

  • Status: A dashboard that describes the health of the overall platform, as well as the status of each individual API being made available via the platform.

  • Change log: A simple list of what has changed on a platform, taking the roadmap and issues that have been satisfied and rolling it into a historical registry that consumers can use to understand what has occurred.

  • Security: Share information about platform security practices and the strategies used to secure platform resources, and share the expectations held of developers when it comes to application security practices.

  • Breaches: Be proactive and communicative around any breaches that occur, providing immediate notification of the breach and a common place to find information regarding current and historic breaches on the platform.

Observability helps build trust with API consumers. In order to develop this trust, platform providers have to invest in APIs in ways that make consumers feel like the platform is stable and reliable. The less transparent that the elements of the platform are, the less likely that API consumers are going to expand and increase their usage of services.

Real-world presence

The final set of recommendations centers on maintaining a real-world presence for the platform. It is important to ensure that the platform does not just have a wide online presence, but is also engaging with API consumers in a face-to-face capacity. There are a handful of ways that leading API providers get their platforms face-time with their community.

  • Meetups: Speaking at and attending meetup events in relevant markets.

  • Hackathons: Throwing, participating in, and attending hackathon events.

  • Conferences: Speaking, exhibiting, and attending conferences in relevant areas.

  • Workshops: Conducting workshops within the enterprise, with partners, and the public.

These four areas help extend and strengthen the relationship between the API platform provider and consumers.

How API developer sandboxes are used to drive adoption

One of the more interesting and forward-thinking aspects of this research is around the delivery of sandbox development, labs, and virtualized environments. Providing a non-production area of a platform where developers can play with API resources in a much safer environment than a live production area can encourage creativity and innovation as well as exploration of the API’s resources.

What we learned

Some of the API providers we interviewed for this proposal had sandbox environments. Their insights into the merits of these environments provided us with some ideas to reduce friction for new developers when onboarding, as well as to help certify applications as they mature with their integrations. Here is what we learned about sandbox environments from the API providers we talked to.

  • Sandboxes are used: Sandbox environments are used, and they do provide value to the API integration process, making them something all API providers should be considering.

  • Sandboxes are not default: Sandboxes are not a default feature of all APIs but have become more critical when PII (personally identifying information) and other sensitive resources are available.

  • Data is virtualized: It was enlightening to see how many of the API providers we talked to provided virtualized data sets and complete database downloads to help drive the sandbox experience.

  • Doing sandboxes well is difficult: We learned that providing sandbox environments that reflect the production environment is, quite simply, hard. It takes significant investment and support to make it something that will work for developers.

  • Safe onboarding: Sandbox environments allow for the safe onboarding of developers and their applications. This helps ensure that only high-quality applications enter into a production environment, which protects the interests of the platform as well as the security and privacy of end-users.

  • Integrated with training: We learned how sandbox environments should also be integrated with other content and training materials. This facilitates access for API consumers to test out the training materials they need while also directly learning about the API.

  • Leverage API management: It was interesting to learn the role that API management plays in being able to deliver both sandbox and production environments. API gateways and management solutions are used to help mock and deliver virtualized solutions, but also to manage the transition of applications from development to a production environment.

Talking to API providers, it was clear that sandboxes provided value to their operations. It was also clear that they aren’t essential for every API implementation and took a considerable investment to do right. API virtualization is a valuable tool when it comes to engaging with API consumers, and it is something that should be considered by most API providers, but it should be approached pragmatically and realistically, with an awareness of both the costs as well as the benefits of moving from transition to production environments.

What our thoughts are

Sandboxes, labs, and virtualized environments are commonplace across the API sector but are not as ubiquitous they should be. We commend the presence of virtualized building blocks for any API that is dealing with sensitive data. A sandbox should be a default aspect of all API platforms, but should be especially applied to help ensure quality control as part of the API journey from development to production. Here are some of the building blocks we recommend when looking at structuring a sandbox environment for a platform.

  • Virtualize APIs: Provide virtualized instance of APIs and a sandbox catalog of API resources.

  • Virtualize data: Provide virtualized and synthesized data along with APIs in order to create as realistic an experience as possible.

  • Virtualized instances: Consider the availability of virtualized instances of an API as computable instances on major cloud platforms, allowing for the deployment of sandboxes anywhere.

  • Virtualized containers: Consider the availability of virtualized instances of an API as containers, allowing API sandboxes to be created locally, in the cloud, and anywhere containers run.

  • Bake into onboarding: Make a sandbox environment a default requirement in the API onboarding process, providing a place for all developers to learn about what a platform offers and pushing applications to prove their value, security, and privacy before entering a production environment.

  • Applications: Center the sandbox experience on the application by certifying it meets all the platform requirements before allowing it to move forward. All developers and their applications get access to the sandbox, but only some applications will be given production access.

  • Certification: Provide certification for both developers and applications. Establishing a minimum bar for what is expected of applications before they can move into production helps developers understand what it takes to move an application from sandbox to distribution, which ensures a high-quality application experience at scale.

  • Showcase: Always provide a showcase for certified applications as well as certified developers. Allow for the browsing and searching of applications and developers, while also highlighting them in communications and other platform resources.

When it comes to API resources that contain sensitive data, virtualized APIs, data, and environments are essential. They should be a default part of ensuring that developers push only high-quality applications to production by forcing them to prove themselves in a sandbox environment first.

Types of metrics for measuring adoption and making decisions

This area of our research overlaps somewhat with the earlier section on measuring success, but here, we provide a more precise look at what can be measured to help quantify success while also ensuring that findings are used as part of the decision-making process throughout the API journey.

What we learned

Our interviews reminded us that it is useful to consider that not all API providers have a fully fleshed out strategy for measuring activity across their platforms. However, we did come away with some interesting lessons from those providers that were using metrics to drive API decision making.

  • Look at it as a funnel: Treat API outreach and engagement as a sales and marketing funnel. Attract as many new users as you can, but then profile the target demographic to try to understand who they are and what their working objectives comprise. From there, devote efforts to incentivizing users to “move down the funnel” through the sandbox environment and eventually to production status. In short, treat API operations like a business and platform users like they are customers.

  • Do not have formal metrics: It was illuminating to also learn that some providers felt that having an overly formal metrics strategy might constrain developer outreach and engagement. Providing words of caution when it comes to measuring too much, as well as only examining data when it comes to making critical decisions, can keep outreach efforts more constructively interacting with API consumers regarding their needs.

  • API keys registered: For data accessibility purposes, it is worthwhile to ensure that all developers have an application and API key before they can access any API resources. Requiring all internal, partner, and eternal developers to pass along their API key with each API call allows all platform activity to be measured, tracked, and used as part of the wider platform decision-making process.

  • Small percentage of users: We also heard that it is common for a small percentage of the overall platform users to generate the majority of API calls to the platform. This makes it important to measure activity on the platform in terms of which users are the most salient (and thereby driving the majority of value on a platform).

  • Amount of investment: Importantly, the usage rates of a platform’s resources can provide a strong justification for investing more resources into the platform’s success, making tracking that data of paramount importance. This transforms investment into a data-driven decision that responds to the actual needs of the platform.

The interview portion of our research provided a valuable look at how API providers are measuring activity across their platforms. Data and metrics are not only being used to define success, but are also used as part of the ongoing decision making process around the direction API providers take their platform, particularly when it comes to measuring adoption of API resources across a platform.

What our thoughts are

When it comes to measuring adoption and understanding how API consumers are putting resources to work, we recommend starting small. Activity tracking is something that will change and evolve as the organization develops a better understanding of platform resources and the interests of internal stakeholders, partners, and 3rd party consumers. These are just a handful of areas we recommend collecting data on to begin with.

  • Traffic: Measure and understand traffic (network and otherwise) across the platform developer portal.

  • New accounts: Track and profile all new accounts signing up for API access.

  • New applications: Track and profile all new applications registered for access.

  • Active applications: Measure and track the usage of the active platform applications.

  • Number of API calls: Understand how many APIs are being called in different dimensions.

  • Conversation: Measure all conversation happening across the platform and use these estimates to develop awareness.

  • Support: Measure all support activity in order to pinpoint the needs of API consumers.

  • Personas: Quantify the different types of consumers who are putting a platform to use.

Begin here when it comes to tracking: develop an awareness of the community and get to know what is important. Then expand from there. Add and remove the metrics that make sense for your organization without tracking metrics for no reason (i.e. all tracking should add value to the API platform or its decision making process).

Structuring and staffing outreach programs

Each platform will have its own mandate for how API programs should be staffed, but there are some common patterns that exist across the space.

What we learned

The API providers we talked to had a lot to share about what it takes to staff their operations, including their structures (or in a few cases lack thereof!).

  • Dedicated evangelist: Make sure there is a dedicated evangelist to help talk-up and support the platform.

  • Include marketing: Include the marketing team in conversations around amplifying the platform and its presence.

  • Provide support: Invest in the resources to support all aspects of the platform effectively, not just those that are consumer-facing or particularly visible.

  • Conduct regular calls: Conduct regular calls with internal, partner, and external stakeholders in order to bring everyone together to discuss the progress of the platform.

  • Use a CRM for automation: Put a CRM to use when it comes to tracking and automating outreach efforts for the platform. Do not reinvent the wheel; leverage an existing service to track all of the details that can be automated.

  • Include other teams: Do not just invest in an isolated API team; make sure other teams across the organization are included in the API conversation.

  • Develop an in-person presence: Make sure to obtain human resources that can be sent to meetups, conferences, and other in-person events so that the organization can expanding and strengthening the presence of the platform.

  • Speak to leadership: Regularly invest time to report platform results and progress to leadership, making sure they understand the overall health and activity of the platform.

We learned that a dedicated evangelist is essential, as well as significant investments in marketing and support. It was good to hear how important in-person events were, supporting stakeholders and leadership when it came to overall outreach efforts. Overall, the conversation we had reflects what we have been seeing across the landscape with other public and private sector providers.

What our thoughts are

Echoing what we heard from our conversations with API providers, we have some advice when it comes to structuring and allocating resources to API efforts. This is a tough area to generalize because different platforms will have different needs, but there are well established traits of successful API providers, with the following characteristics making the top of the list.

  • Dedicated program: Establish a formal program for overseeing API operations across an organization to make sure it gets the attention it needs.

  • Dedicated team: Allocate a dedicated team to the API program and platform to represent its needs and push for its continued advancement.

  • Business involvement: Make sure to involve business groups in the conversation, bringing them in as stakeholders to give their thoughts on the organization’s API program.

  • Marketing involvement: Make sure marketing teams play an influential role in amplifying the message coming from a platform. This is especially important to ensure that a platform does not just speak to developers, but to consumers and users as well.

  • Sales involvement: Ensure that a platform has the sales resources to actually close deals when necessary. This ensures that a platform has continuing end-user participation and the resources it needs to function. Remember, though, that sales is not always about selling commercial solutions.

  • External users: Make a place for external actors to take part in advancing the API-relevance conversation. External users can often rise to highly influential levels within a community, and this influence can be put to work assisting with outreach efforts (but only if the culture of a platform allows for it).

  • Contractors: Consider how vendors and contractors will be contributing to the overall outreach effort by creating a means for vendors to assist with logistics and communication channels, allowing the core team to focus on moving the platform forward while contractors tackle the details.

It will take dedicated resources to move the API conversation forward at a large organization. However, it will also take the involvement of other stakeholders to get the business and political capital to legitimately spark the platform initiative. How a program gets structured, and the amount of resources dedicated to evangelism, communication, support, and other critical areas will set the tone for the platform and determine the overall health and viability of the API.


One unorthodox part of our research involved asking API providers about the things they felt would contribute to the failure of their API platform. Below, we have collected some thoughts about the “anti-patterns” that might generate friction on the platform, chase developers away, or make things harder for everyone involved.

What we learned

The API providers we talked to had plenty of ideas for how to run developers off and make integration with platform resources harder. We’ve provided a list of things API providers can avoid when operating their platforms and when reaching out to developers. (To be clear, each of the things presented in the list below is a bad practice — the bolded phrase is a “mistake” an API provider could make, and the text that follows further explains the nature of the poor practice.)

  • Do not take a build it and they will come approach: Building API operations with tremendous resource investment before consumers ask for certain functions or resources is a poor way to achieve stable platform growth.

  • Do not reach out to developers: Not being proactive about contacting developers makes it hard to build working relationships that clarify development needs.

  • Hand built documentation: Providing hand-crafted, bloated, or out of date documentation is not only difficult to maintain, it reduces the value of the API to developers.

  • Breaking changes: Changing the platform too often or too fast may introduce too many breaking changes for developers to deal with, reducing the platform’s effectiveness.

  • Do not communicate: Not communicating platform operation updates leaves developers in the dark about what is happening with the very tool they rely on.

  • Do not listen to your developers: Not listening to developers or including their feedback in the roadmap is sure to eventually run developers off.

  • Do not measure happiness: Measure everything except for the happiness of developers, because such a metric (if you can even operationalize it as such) will never really lead to understanding if they are truly happy about how the platform is being run.

  • Gated content: Putting documentation, content, and other resources behind a login or paywall, or else restricting what developers have access to, is a great way to get developers to ignore your platform.

  • Do not provide a developer edition: Avoid providing developers with a set of APIs to play with simply for the sake of “experimentation.” Without being able to see the value of real, production-strength applications, users will not be building their projects on the platform any time soon.

  • Do not reach out to partners: Focusing on general developers without identifying and reaching out to potential partners can rob a platform of trusted allies, who might have otherwise facilitated operations, integrations, and even broader application development.

It was clear that the API providers we interviewed were aware of the pitfalls that could jeopardize an API’s success. They provided us with a comprehensive look at what an organization should avoid when it comes to operations and investment.

What our thoughts are

Adding to what the API providers mentioned during their interviews, we have some additional recommendations based on some common deficiencies we have seen. These are the areas all API providers should be investing in to strengthen their operations and to avoid the anti-patterns highlighted so far.

  • Documentation: Make documentation a priority by keeping it simple, updated, and interactive for developers.

  • Entry level: Ensure there is entry-level access to a platform, allowing developers to onboard without commitments or procedural friction.

  • Communication: Develop a robust communication strategy for ensuring a platform has a regularly updated stream of new content about what is happening.

  • Support: Ensure that a platform is supported, and that API consumer’s questions are being answered in a timely manner.

  • Feedback loops: Make sure that feedback loops exist and are strengthened by communication, support, and actually listening to developers’ needs.

  • Evangelism: Invest in evangelism amongst leadership, partners, 3rd party developers and all stakeholders to make sure the platform is always being spoken for.

  • Observability: Insist on observability for all components involved in operating a platform to maximize measurements and comprehension of the system.

  • Partners: Seek out partners. They are critical to taking the platform to the next level. Cultivate developers and applications, and produce strong partners who can help take things into the future.

We see anti-patterns as deficient areas of platform operations that can largely be avoided with proper time and resource investments.

Future plans

We concluded our provider interviews with a few questions on what they believe the future holds. Their visions for their growth and development can serve as strong examples and recommendations for what other platforms can include in their own plans.

What we learned

It was interesting to learn about the desires our interviewees possessed when it came to future investment in their platforms. We have generated this short list of areas that API providers can think about when it comes to building out their roadmap.

  • Go with what works: Make sure to continue investing in and scaling the parts of the platform that are earning attention for their success.

  • Product excellence: Emphasize product excellence over simply responding to new developments.

  • Marketing and evangelism: It has never bad to augment marketing efforts to broadcast information about a platform.

  • Attend conferences: Increase the platform’s presence at relevant conferences.

  • Throw hackathons: Invest in throwing hackathons to encourage developers to do more.

  • Conduct conferences: Invest in and produce conferences that support the API community.

  • Building community: Do what it takes to keep building and strengthening the community.

  • Publish more to GitHub: Publish more code, content, and other resources to the GitHub or other version control platform.

  • Make connect more discoverable: Work to make resource more discoverable so that developers can find what they need.

  • Publish to Publish code to, making code open source and available as part of the wider government effort to make resources available.

The common theme we heard from API providers was that allocation for future investment should be spent reinforcing the building blocks already in place that made the API platform successful in the first place. We learned a lot about the motivations and visions of the API providers we interviewed, which helped shape our recommendations for what could be next.

What our thoughts are

With so many possibilities for the path that an API platform’s development can take, it is easy to get caught up in the next step without reflecting on the fact that what is next usually involves reinforcing what is happening now. Our recommendations involve focusing on what matters, and not just what is new, with the following areas of investment:

  • Continue investing in what works: To once again echo our interviewees, continue to invest in building what is already working. Further develop the API platform and its associated vision conversation by looking to what already exists rather than looking for new ways to get things done.

  • Excellence and mastery: Invest in perfecting the process, refining how things get done, and operating the platform in a way that benefits everyone involved. Doing it well, and do it it right, will pay off in the long run.

  • Involve other teams: Expand involvement with the API to include other teams across an organization. This helps distribute the workload of operating the API platform and allows all subgroups within an organization to have a voice in the future of the API.


To produce this research, we spoke with leading API providers from across the public and private sector while also leveraging eight years of analysis gathered from directly studying the API sector. This research should provide a wealth of options to consider when it comes to helping the VA be more effective in reaching out to developers. However, this is not meant to be a complete list of building blocks to consider, but rather, is meant to present a selection of proven elements that can be implemented with the right teams to execute. While things like API documentation are critical, there is no single element of this research that will make or break API outreach efforts; when the right elements are combined and executed properly, the results can be extremely positive.

This research reflects the experience of platform providers like SalesForce who have been iterating upon their API platforms and engaging with consumers since 2001. It also follows the lead of next generation providers like Twilio who have been making developers happy for almost a decade, while also managing to take their company public. It looks at how CMS, Census, and FEC are approaching the outreach around their API programs, bringing in the unique perspective of federal agencies who are finding success with their APIs. Finally, the insights gathered across these API providers is organized, augmented, and rounded off with insight gathered by the API Evangelist as part of research on the business of APIs, research that has been ongoing since July of 2010.

We want to end this look at developer outreach by emphasizing once again that this is a journey. While there are many common patterns in play across the API sector, no two API platforms are the same. The types of developers attracted to a platform, as well as the ones that remained engaged, will vary depending on the organization, the types of resources being made available, and the tone set by the teams(s) operating the platform. It is up to the VA to decide what type of platform they will operate and what kind of tone they will set when reaching out to developers. There will not be any single right answer to how the VA should be reaching out to new developers, but with the right amount of planning, communication, support, and observability, the VA will undoubtedly find its footing.

Appendix A: interview questions

For each interview, we asked the following questions:

  1. What role do you play within the organization?

  2. What is the purpose and scope of your API developer outreach program?

  3. What does success look like for you?

  4. What are the key elements or practices (e.g, documentation, demos, webinars, conferences, blog posts) that you’re using to drive and sustain effective adoption of your API(s)?

  5. Do you make use of an API developer sandbox to drive and sustain adoption? If so, please describe how you’ve designed that environment to be useful and usable to developers.

  6. What types of metrics do you use to measure adoption effectiveness and to inform future decisions about how you evolve your program?

  7. How is your outreach program structured and staffed? How did it start out and evolve over time?

  8. Imagine that you’re charged with ensuring the complete failure of an API developer outreach program. What things would you do to ensure that failure?

  9. What big ideas do you have for evolving your outreach program to make it even more effective?

  10. Any other thoughts you’d like to share? If so, please feel free!

Appendix B: CMS Blue Button API interview notes

1. What role do you play within the organization?

Product Manager.

2. What is the purpose and scope of your API developer outreach program?

CMS is offering several APIs. One approach is put it out there and hope they come. Second approach is leveraging APIs on the Socrato platform and hoping there’s adoption. Third approach is partnership agreements with various private partners.

Purpose of the Blue Button outreach program is to drive adoption of the API.

3. What does success look like for you?

Worked with various stakeholders to define the metrics in terms of value. For example, number of unique organizations who are experimenting with the API. Originally set a target of 500 organizations. Up to 450 currently. Use it as a proxy measurement of value. Not sure how beneficiaries are benefiting yet, but adoption is proxy indicator.

Also measuring number of beneficiaries who have linked their data to Blue Button API — for example, Google Verily.

4. What are the key elements or practices (e.g, documentation, demos, webinars, conferences, blog posts) that you’re using to drive and sustain effective adoption of your API(s)?

Documentation is the first key element. Originally hosted documentation on GitHub pages, but now using

Had challenges over the year making clear what Blue Button is, value, etc.

Relaunched during recent HIMSS conference. Resulted in a number of sign-ups from press.

Set up a blog to provide a getting started guide, how sign-up works, etc. Working pretty well.

Assigned a designated Developer Evangelist, who pushes content, participates in forums, and hits the niche conference circuit.

5. Do you make use of an API developer sandbox to drive and sustain adoption? If so, please describe how you’ve designed that environment to be useful and usable to developers.

Sandbox has been a big part. Have a synthetic dataset. In healthcare, this is essential from a privacy standpoint.

Have had challenge with synthetic data in terms of making them realistic.

Have a streamlined process for accessing and onboarding into environment. Experience is not currently great, and working on improving.

Developer portal is only for sandbox environment. No portal for production, so disjointed at this point.

6. What types of metrics do you use to measure adoption effectiveness and to inform future decisions about how you evolve your program?

Look at the adoption as a funnel. That has helped to drive a culture shift around how folks think about metrics and the role they play.

Top of funnel is evangelism/traffic/etc., portal sign-ups, registered an app, and how many of those who have registered made API calls.

7. How is your outreach program structured and staffed? How did it start out and evolve over time?

Have a developer evangelist.

Periodically, team gets on phone with developer evangelist and talks about ideas for building awareness and driving adoption.

Using email + CRM tools for outreach. Trying to improve marketing automation.

8. Imagine that you’re charged with ensuring the complete failure of an API developer outreach program. What things would you do to ensure that failure?

Don’t take a “build it and they will come” approach.

Not acting quickly enough on insights gained from the funnel process, including reaching out to individuals to help them through the process (i.e., proactive outreach).

9. What big ideas do you have for evolving your outreach program to make it even more effective?

Double down on what’s working to incrementally grow — conferences, webinars, etc.

Serving as a blueprint for other organizations, particularly at a state & local level.

10. Any other thoughts you’d like to share? If so, please feel free!


Appendix C: Census interview notes

1. What role do you play within the organization?

Developer engagement lead, serving as the comms arm for Census’ API efforts. First-line of defense for any developer engagement. Participate in hackathons, etc.

Also working on CitySDK. This was in response to the observation that developers were having trouble working with Census APIs. SDK currently not being maintained because lost lead developer and funding for it. Personally learning how to develop in order maintain myself.

2. What is the purpose and scope of your API developer outreach program?

Save developers time and help them understand the nuances of Census data and how to use the data. Engage in communications and help inform the development of API products.

3. What does success look like for you?

Happy developers.

4. What are the key elements or practices (e.g, documentation, demos, webinars, conferences, blog posts) that you’re using to drive and sustain effective adoption of your API(s)?

Proactive engagement: work on driving the government’s engagement in National Day of Civic Hacking in collaboration with NASA and Code for America. Hackathons are great for user research and testing new features.

Reactive: have a Slack and Gitter channel.

Haven’t tried blog posts yet. Thinking about interviewing developers who are using APIs and turning their stories into blog posts. Haven’t been able to get legal approval yet for that.

Being able to figure out what data Census has and how that data can be made available to developers is key.

Webinars are good, especially those focused on showing how to use Census data and build something simple using the API.

Use a data search tool — American FactFinder; developers can use this to find out what variables they are interested in and then trace that data back to an API that they can use to access programmatically.

5. Do you make use of an API developer sandbox to drive and sustain adoption? If so, please describe how you’ve designed that environment to be useful and usable to developers.

No, haven’t done anything like yet. Have a discovery tool that is part of the API.

6. What types of metrics do you use to measure adoption effectiveness and to inform future decisions about how you evolve your program?

Initially focused on number of API keys registered. Starting focusing on metrics of use. A small number of users drive 80% of the API use. Developers tend to move data into their environment for performance purposes (e.g., caching). Plus, they worry about government shutting down and data not being accessible.

7. How is your outreach program structured and staffed? How did it start out and evolve over time?

One person focused on outreach.

Entire team dedicated to building the APIs and making the data available and accessible. Each product gets its own endpoint; there are about 30 now and planning to do 70 more.

8. Imagine that you’re charged with ensuring the complete failure of an API developer outreach program. What things would you do to ensure that failure?

Create terrible, hand-rolled documentation with a lot of pictures; don’t give developers a channel to communicate; don’t listen to them; don’t give them a way to test out data before granting a key; and don’t have metrics for measuring developer happiness and just focus on usage metrics.

9. What big ideas do you have for evolving your outreach program to make it even more effective?

Focus more on product excellence and marketing. A lot of developers don’t like being pushed to. Most developers go to hackathons for social interaction and career progression, not because they love working with your data and using your APIs.

10. Any other thoughts you’d like to share? If so, please feel free!

Instead of trying to focus too much on attracting random developers, focus on the developers who are engaged now and reach out to them. Would like to introduce a CRM system to help manage these relationships better.

Learned it’s important to grab as much data during the registration process in order to gain better insight into developer intent, behavior, and characteristics. Found it’s very hard to get information after developers have gained access; they don’t typically respond to email requests for information.

Hackathons, etc. are huge investment of time and resources.

Biggest lesson learned is to always focus on the principle of how to make it as easy for the developers as possible.

Make heavy use of GraphQL because it’s introspective and helps developers understand the API in greater detail. Like GraphQL because it can evolve without breaking things.

Appendix D: OpenFEC interview notes

1. What role do you play within the organization?

Tech Lead at FEC, mostly focused on OpenFEC. Involved in FEC campaign finance data for ten years.

2. What is the purpose and scope of your API developer outreach program?

Don’t have an overarching formal approach in place yet, but do provide support to developers through a variety of channels when they reach out.

3. What does success look like for you?

Number one measure of success is providing developers accurate data, and making sure that is available at all times. Also making sure that developers can find the data that they need.

4. What are the key elements or practices (e.g, documentation, demos, webinars, conferences, blog posts) that you’re using to drive and sustain effective adoption of your API(s)?

Don’t have a formally developer outreach program. Have small team of developers, designers, content designers, and product managers.

Would like to be more proactive about engaging.

Do have some mechanisms for getting feedback. For example, the project is open source, which encourages developers to add issues, contribute, etc. Developers can send emails to [email protected]. Existing team tries to get back as quickly as possible. Would like to have a ticket management system to help facilitate workflow around support. Do have a google group in which community of developers can ask and answer questions.

Do have a developer page. And work hard to keep those up-to-date.

Use GSA’s API umbrella to manage users, which handles rate limiting and caching.

Have a try-it-out feature on developer page powered by Swagger API, and can just put params in to see how the API works.

5. Do you make use of an API developer sandbox to drive and sustain adoption? If so, please describe how you’ve designed that environment to be useful and usable to developers.

Don’t have a sandbox, but do provide instructions for setting up locally. And also provide a sample database that can be copied. Since all data is public, don’t have to worry about PII. Amazon provides a free sandbox environment to anyone with .gov domain that can be used to set-up a test environment.

6. What types of metrics do you use to measure adoption effectiveness and to inform future decisions about how you evolve your program?

Don’t have formal metrics. Using the GSA API Umbrella, there is some data available, not currently using that data to drive decisions.

7. How is your outreach program structured and staffed? How did it start out and evolve over time?

The existing team of developers, etc. are providing outresearch support.

8. Imagine that you’re charged with ensuring the complete failure of an API developer outreach program. What things would you do to ensure that failure?

Making breaking changes and don’t tell anyone; not responding to and fixing data quality issues, which would undermine the credibility of the API; couldn’t serve the data in an efficient manner.

9. What big ideas do you have for evolving your outreach program to make it even more effective?

Have discussed holding a hackathon or conference, similar to what Blue Button is doing.

Holding a quarterly developer conference call to starting answering questions and discuss ideas.

Regardless of activity, starting to build a community.

Pushing our code to to increase awareness.

10. Any other thoughts you’d like to share? If so, please feel free!

There are commercial restrictions around the use of open FEC data.

Appendix E: Salesforce interview notes

1. What role do you play within the organization?

Vice President of Developer Relations. My team doesn’t create APIs but we drive awareness and adoption through producing:

  • Technical content

  • Demos & sessions at events

  • Tools like SDKs and interactive docs

  • Marcom (social, email, etc)

  • Community Building

2. What is the purpose and scope of your API developer outreach program?

Unlike companies who solely monetize services, our primary purpose is to enable developers to create custom integrations with Salesforce.

As an advanced enterprise software platform, its critical that Salesforce work well with all the other enterprise apps you might have. In addition, many of our customers are building custom web or mobile apps that need access to customer data.

Because we are a platform, our purpose is not limited to just “API outreach” but is inclusive both of our APIs and also our app development platform.

Some of the primarily use-cases for our APIs are to extract data for archival purpose, surface customer data in third-party or bespoke apps, or to enable business systems to work together in other ways. We also have a family of machine learning APIs known as Einstein Vision and Einstein Language that can be used by any application to create predictions from unstructured images and text.

3. What does success look like for you?

Ultimately, we know that our customers are demanding more skilled Salesforce Developers every day to support their custom implementations so our primary metrics are monthly signups and active monthly usage.

Our goal is to keep the growth of our developer population in line with our overall customer growth to ensure there are enough developers in the ecosystem to service our customers needs.

We also measure job postings for Salesforce Developers, traffic to our website, engagement with our events like Dreamforce and TrailheaDX, and usage of our online learning portal

4. What are the key elements or practices (e.g, documentation, demos, webinars, conferences, blog posts) that you’re using to drive and sustain effective adoption of your API(s)?

Blogging, webinars, documentation (including an API Explorer), training classes, sample code, first-party events (we do regional workshops called DevTrails, large regional events called Salesforce World Tours, and big global events called Dreamforce and TrailheaDX)

In addition, we have built a substantial community program with over 200 developers groups around the world and an MVP program to recognize top contributors in the community. We’re in the process of expanding our open source footprint (sample code, apps, and SDKs).

5. Do you make use of an API developer sandbox to drive and sustain adoption? If so, please describe how you’ve designed that environment to be useful and usable to developers.

We have a free environment called the Salesforce Developer Edition that anyone can sign up for. There is no expiration date so you can use it as long as you’d like, and you’re allowed to sign up for as many as you’d like for the times that you need a “clean sandbox.”

We’ve also tightly integrated these developer editions into the Trailhead learning platform, so that as a developer is going through an online course (called a module) or a tutorial (called a project) they can actually complete hands-on challenges in their developer environment and get validation that they have done it correctly.

To protect our business interests, these developer environments have limits in terms of API usage, storage, user licenses, etc. With these limits, we do our best to find a balance between empowering the developers and protecting the business. And we have a process where developers can request increased limits.

6. What types of metrics do you use to measure adoption effectiveness and to inform future decisions about how you evolve your program?

We use our CRM platform to measure all the ways we touch our developers and how that impacts success.

7. How is your outreach program structured and staffed? How did it start out and evolve over time?

When we launched the program, we started small. 1-2 evangelists, a program manager for community/events, and a web developer. It grew from there.

We don’t share details about our current team size publicly. However, the key components of our program are as follows with approximate percentages:

  • Marketers (12%)

  • Evangelists (35%)

  • Community Program Managers (12%)

  • Event Producers/Program Managers (13%)

  • Marketing Operations: Email, Development, Creative, etc (25%)

8. Imagine that you’re charged with ensuring the complete failure of an API developer outreach program. What things would you do to ensure that failure?

Gate all the content.

Don’t provide a developer edition.

Don’t share use-cases or sample code.

Don’t find any partners.

Don’t engage with your users or help them be successful.

9. What big ideas do you have for evolving your outreach program to make it even more effective?

We have a ton of content but it’s not all discoverable.

Working on making our pages more data-driven and dynamic so we can expose all our resources.

We’re also moving a lot of our content to GitHub as well as creating a more organized process to store our code samples.

Many of them are orphaned in blog posts and other places.

10. Any other thoughts you’d like to share? If so, please feel free!


Having The Dedication To Lead An API Effort Forward Within A Large Enterprise Organization

I work with a lot of folks who work in large enterprise organizations, institutions, and government agencies who are moving the API conversation forward within their groups. I’m all too familiar with what it takes to move forward the API conversation within large, well established enterprise organizations. However, I am the first to admit that while I have a deep understanding of what it involves, I do not have the fortitude to actually lead an effort for the sustained amount of time it takes to actually make change. I just do not have the patience and the personality for it, and I’m eternally grateful for those that do.

There are regular streams of emails in my inbox from people embedded within enterprise organizations, looking for guidance, counseling, and assistance in moving forward the API conversation at their organizations. I am happy to provide assistance in an advisory capacity, and consulting with groups to help them develop their strategies. A significant portion of my income comes from conducting 1-3 day workshops within the enterprise, helping teams work through what they need to. There is one thing I cannot contribute to any of these teams, the dedication and perseverance it will need to actually make it happen.

It takes a huge amount of organization knowledge to move things forward at a large organization. You have to know who the decision makers are, and who are the gatekeepers for all of the important resources–this is knowledge you have to acquire by being embedded, and working within an organization for a very long time. You just can’t walk in the door and be able to make sense of things within days, or weeks. You have to be able to work around schedules, and personalities–getting to know people, and truly begin to understand their motivations, and willingness to contribute, or whether they’ll actually decide to work against you. The culture of any enterprise organization will be the most important area of concern for you as you craft and evolve your API strategy.

I often wish I had the fortitude to work in a sustained capacity within a large organization. I’ve tried. It just doesn’t fit my view of the world. However, I am super thankful for those of you who are. I’m super happy to help you in your journey. I’m happy to help you think through what you are experiencing as part of my storytelling here on my blog–just email me your questions, thoughts, and concerns. I’m happy to anonymize as I work through my responses here on the blog, about 60% of the stories you read here are the anonymized result of emails I receive from y’all. I’m happy to vent for you, and use you as my muse. I’m also happy to help out in a more dedicated capacity, and provide my consulting assistance to your organization–it is what I do, and how I pay the bills. Let me know how I can help.

Having The Dedication To Lead An API Effort Forward Within A Large Enterprise Organization

I work with a lot of folks who work in large enterprise organizations, insttutions, and government agencies who are moving the API conversation forward within their groups. I’m all too familiar with what it takes to move forward the API conversation within large, well established enterprise organizations. However, I am the first to admit that while I have a deep understanding of what it involves, I do not have the fortitude to actually lead an effort for the sustained amount of time it takes to actually make change. I just do not have the patience and the personality for it, and I’m eternally grateful for those that do.

There are regular streams of emails in my inbox from people embedded within enterprise organizations, looking for guidance, counseling, and assistance in moving forward the API conversation at their organizations. I am happy to provide assistance in an advisory capacity, and consulting with groups to help them develop their strategies. A significant portion of my income comes from conducting 1-3 day workshops within the enterprise, helping teams work through what they need to. There is one thing I cannot contribute to any of these teams, the dedication and perseverence it will need to actually make it happen.

It takes a huge amount of organiation knowledge to move things forward at a large organiation. You have to know who the decision makers are, and who are the gatekeepers for all of the important resources–this is knowledge you have to acquire by being embedded, and working within an organization for a very long time. You just can’t walk in the door and be able to make sense of things within days, or weeks. You have to be able to work around schedules, and personalities–getting to know people, and truly begin to understand their motivations, and willingness to contribute, or whether they’ll actually decide to work against you. The culture of any enterprise organization will be the most important area of concern for you as you craft and evolve your API strategy.

I often wish I had the fortitude to work in a sustained capacity within a large organiation. I’ve tried. It just doesn’t fit my view of the world. However, I am super thankful for those of you who are. I’m super happy to help you in your journey. I’m happy to help you think through what you are experiencing as part of my storytelling here on my blog–just email me your questions, thoughts, and concerns. I’m happy to anonymize as I work through my responses here on the blog, about 60% of the stories you read here are the anonymized result of emails I receive from y’all. I’m happy to vent for you, and use you as my muse. I’m also happy to help out in a more dedicated capacity, and provide my consulting assistance to your organization–it is what I do, and how I pay the bills. Let me know how I can help.

Justifying My Existence In Your API Sales And Marketing Funnel

I feel like I’m regularly having to advocate for my existence, and the existence of developers who are like me, within the sales and marketing funnel for many APIs. I sign up for a lot of APIs, and have the pleasure of enjoy a wide variety of on-boarding processes for APIs. Many APIs I have no problem signing up, on-boarding, and beginning to make calls, while others I have to just my existence within their API sales and marketing funnel. Don’t get me wrong, I’m not saying that I shouldn’t be expected to justify my existence, it is just that many API providers are setup to immediately discourage, create friction for, and dismiss my class of API integrator–that doesn’t fit neatly into the shiny big money integration you have defined at the bottom of your funnel.

I get that we all need to make money. I have to. I’m actually in the business of helping you make money. I’m just saying that you are missing out on a significant amount of opportunity if you only focus on what comes out the other side of your funnel, and discount the nutrients developers like me can bring to your funnel ecosystem. I’m guessing that my little domain does return the deal size scope you are looking for, but I think you are putting too much trust into the numbers provided to you by your business intelligence provider. I get that you are hyper focused on making the big deals, but you might be leaving a big deal on the table by shutting out small fish, who might have oversized influence within their organization, government agency, or within an industry. Your business intelligence is focusing on the knowns, and doesn’t seem very open to considering the unknowns.

As the API Evangelist I have an audience. I’ve been in business since 2010, so I’ve built up an audience of enterprise folks who read what I write, and listen to “some” of what I say. I know people like me within the federal government, within city government, and across the enterprise. Over half the people I know who work within the enterprise, helping influence API decisions, are also kicking the tires of APIs at night. Developers like us do not always have a straightforward project, we are just learning, understanding, and connecting the dots. We don’t always have the ready to go deal in the pipeline, and are usually doing some homework so that we can go sell the concept to decision makers. Make sure your funnel doesn’t keep us out, run us away, or remove channels for our voice to be heard.

In a world where we focus only on the big deals, and focus on scaling and automating the operation of platforms, we run the risk of losing ourselves. If you are only interested in landing those big customers, and achieving the exit you desire, I understand. I am not your target audience. I will move. It also means that I won’t be telling any stories about what you are doing, building any prototypes, and generally amplifying what you are doing on social media, and across the media landscape. Providing many of the nutrients you will need to land some of the details you are looking to get, generating the internal and external buzz needed to influence the decision makers. Providing real world use cases of why your API-driven solution is the one an enterprise group should be investing in. Make sure you aren’t locking us out of your platform, and you are investing the energy into getting to know your API consumers, more about what their intentions are, and how it might fit into your larger API strategy–if you have one.

An API Value Generation Funnel With Metrics

I’ve had several folks asking me to articulate my vision of an API centric “sales” funnel, which technically is out of my wheelhouse in the sales and marketing area, but since I do have lots opinions on what a funnel should look like for an API platform, I thought I’d take a crack at it. To help articulate what is in my head I wanted to craft a narrative, as well as a visual to accompany how I like to imagine a value generation funnel for any API platform.

I envision a API-driven value generation funnel that can be tipped upside down, over and over, like an hour glass, generating value is it repeatedly pushes API activity through center, driven by a healthy ecosystem of developers, applications, and end-users putting applications to work / use. Providing a way to generate awareness and engagement with any API platform, while also ensuring a safe, reliable, and secure ecosystem of applications that encourage end-user adoption, engagement, and loyalty–further expanding on the potential for developers to continue developing new applications, and enhancing their applications to better serve end-users.

I am seeing things in eleven separate layers, something I’ll keep shifting and adjusting in future iterations, but I just wanted to get a draft funnel out the door:

  • Layer One - Getting folks in the top of the funnel.
    • Awareness - Making people aware of the APIs that are available.
    • Engagement - Getting people engaged with the platform in some way.
    • Conversation - Encouraging folks to be part of the conversation.
    • Participation - Getting developers participating on regular basis.
  • Layer Two
    • Developers - Getting developers signing up and creating accounts.
    • Applications - Getting developers signing up and creating applications.
  • Layer Three
    • Sandbox Activity - Developers being active wthin the sandbox environment.
  • Layer Four
    • Certifed Developers - Certifying developers in some way to know who they are.
    • Certified Application - Certifying applications in some way to ensure quality.
  • Layer Five
    • Production Activity - Incentivizing production applications to be as active as possible.
  • Layer Six
    • Value Generation (IN / OUT) - Driving the intended behavior from all applications.
  • Layer Seven
    • Operational Activity - Doing what it takes internally to properly support applications.
  • Layer Eight
    • Audit Developers - Make sure there is always a known developer behind the application.
    • Audit Applications - Ensure the quality of each application with regular audits.
  • Layer Nine
    • Showcase Developers - Showcase developers as part of your wider partner strategy.
    • Showcase Applications - Showcase and push for application usage across an organization.
  • Layer Ten
    • Loyalty - Develop loyal users by delivering the applications that user are needing.
    • End-Users - Drive end-user growth by providing the applications end-users need.
    • Engagement - Push for deeper engagement with end-users, and the applications they use.
    • End-Usage - Incentivize the publishing and consumption of all platform resources.

I’m envisioning a funnel that you can turn on its head over and over and generate momentum, and kinetic energy, with the right amount of investment–the narrative for this will work in either direction. Resulting in a two-sided funnel both working in concert to generate value in the middle.

To go along with this API value generation funnel, I’m picturing the following metrics being applied to quantify what is going on across the platform, and the eleven layers:

  • One - Unique visitors, page views, RSS subscribers, blog comments, tweets, GitHub follows, forks, and likes.
  • Two - New developers and new applications.
  • Three - API calls on sandbox API resources.
  • Four - New certified developers and applications.
  • Five - API calls in the production API resources.
  • Six - GET, POST, PUT, DELETE on different types of resources.
  • Seven - Support requests, communication, and other new resources.
  • Eight - Number of developers and applications audited.
  • Nine - Number of new and existing developers and applications showcased.
  • Ten - Number of end-users, sessions, page views, and other activity.

Providing a stack of metrics you can use to understand how well you are doing within each layer, understanding not just the metrics for a single area of your operations, but how well you are doing at building momentum, and increasing value generation. I hesitate to call this a sales funnel, because sales isn’t my jam. It is also because I do not see APIs as something you always sell–sometimes you want people contributing data and content into a platform, and not always just consuming resources. A well balanced API platform is generating value, not just selling API calls.

I am not entirely happy with this API value generation funnel outline and diagram, but it is a good start, and gets me closer to what I’m seeing in my head. I’ll let it simmer for a few weeks, engage in some conversations with folks, and then take another pass at refining it. Along the way I’ll think about how I would apply to my own API platform, and actually take some actions in each area, and begin fleshing out my own funnel. I’m also going to be working on a version of it with the CMO at, and a handful of other groups I’m working with on their API strategy. The more input I can get from a variety of API platforms, the more refined I can make this outline and visual of my suggested API value generation funnel.

My API Storytelling Depends On The Momentum From Regular Exercise And Practice

I’ve been falling short of my normal storytelling quotas recently. I like to have at least 3 posts on API Evangelist, and two posts on each day. I have been letting it slip because it was summer, but I will be getting back to my regular levels as we head into the fall. Whenever I put more coal in the writing furnace, I’m reminded of just how much momentum all of this takes, as well as the regular exercise and practice involved, allowing me to keep pace in the storytelling marathon across my blog(s).

The more stories I tell, the more stories I can tell. After eight years of doing this, I’m still surprised abut what it takes to pick things back up, and regain my normal levels of storytelling. If you make storytelling a default aspect of doing work each day, finding a way to narrate your regular work with it, it is possible to achieve high volumes of storytelling going out the door, generating search engine and social media traffic. Also, if you root your storytelling in the regular work you are already doing each day, the chances it will be meaningful enough for people to tune in only increases.

My storytelling on API Evangelist is important because it helps me think through what I’m working on. It helps me become publicly accessible by generating more attention to my work, firing up new conversations, and reenforces the existing ones I’m already having. When the storytelling slows, it means I’m either doing a unhealthy amount of coding or other work, or my productivity levels are suffering overall. This makes my API storytelling a heartbeat of my operations, and a regular stream of storytelling reflects how healthy my heartbeat is from regular exercise, and usage of my words (instead of code).

I know plenty of individuals, and API related operations that have trouble finding their storytelling voice. Expressing that they just don’t have the time or resources to do it properly. Regular storytelling on your blog is hard to maintain, even with the amount of experience I have. Regardless, it is something you just have to do, and you will have mandate that storytelling just becomes a default aspect of your work each day. If you work on it regularly, eventually you’ll find your voice. However, there will always be times where you lose it, and have to work to regain it again. It is just the fight you will have to fight, but ultimately if you continue, it will be totally worth it. I’m very thankful I’ve managed to keep it going for over eight years now, resulting in a pretty solid platform that enables me to do what I do.

Every Moment Is Potentially An API Story

I was on a call for a federal government API platform project with my partner in crime Chris Cairns (@cscairns) of Skylight.Digital. We were back channeling in our Slack channel during the call, when he said, “I always imagine you participating in these things, finding topics you haven’t covered or emphasized from a certain angle, and then writing a blog post in real time.” He was right, I had taken notes on a couple of new angles regarding the testing, monitoring, and understanding performance of APIs involved with federal government projects.

The single conference call resulted in about seven potential stories in my notebook. I’m guessing that only four of them will actually end up being published. However, the conversation does a good job at highlighting my style for generating stories on the blog, which is something that allows me to publish 3-5 posts a day–keeping things as active as I possibly can, generating traffic, and bringing attention to my work. If you’ve ever worked closely with me, you know that I can turn anything into a story, even a story like this, about how I create stories. ;-)

Think of API Evangelist as my public workbench where I work through the projects I’m tackling each day. It is how I make sense of my research, the projects I am working on, and the conversations I am having. All of which generates SEO exhaust, which brings more attention to my work, extends its reach, and ultimately brings in more work. It is a cycle that helps me work through my ideas in a way that forces me to make them more coherent (hopefully) along the way, while also making them immediately available to my partners, customers, and readers.

Chris has been pushing this concept forward and advocating that we be public with as many of the Skylight.Digital responses and proposals as we possibly can, which resulted in me publishing both of our responses to the first, and the second Department of Veteran Affairs (VA) RFIs. He has also been pushing other Skylight.Digital partners to be public with their proposals and responses, which folks were skeptical about at first, but then it started making sense when they see the effect it has, and the publicity it can generate.

This approach to storytelling isn’t something you can do effectively right out of the gate. It takes practice, and regular exercising–I have eight years of practice. However, I feel it is something that anyone can do eventually. You just have to find your own way of approaching it, and work on establishing your own voice and style. It is something that I’ve found to be essential to how I do business, but also something I find to be personally rewarding. I enjoy working through my ideas, and telling stories. It is always the one aspect of my work that I look forward to doing each day, and I feel like something is missing the days I don’t get to craft any posts. I really enjoy that every moment has the potential to be an API story, it really makes each day an adventure for me.

Api Coordination And Communication Across Federal Government Agencies

404: Not Found

Balancing Virtual API Evangelism With In-Person API Evangelism

I haven’t published any stories this week on API Evangelist. I’ve been on the road in Lyon and Paris, France. Giving talks, and conducting workshops about my API lifecycle and governance work. Often times when I go on the road I try to pre-populate the blog with stories, but I’ve been so busy lately with travel and projects that I just didn’t have the time. Resulting in the blog not resembling its usual stream of API rants and stories. While this bothers me, I understand the balance between virtual API evangelism and the need to be present in-person from time to time.

While I feel like I can reach more people virtually, I feel like at least 30% of the time I should be present in-person. It helps re-enforce what I know, and allows me to evolve my work, and learn knew things by exercising my API knowledge on the ground in the trenches within existing organizations, and at conferences, Meetups, and workshops. While exhausting, and often costly, in-person gatherings help build relationships, allowing me to establish deeper connections with people. Helping my work penetrate the thick bubbles that exist around us in our personal and professional lives. I’m always exhausted after traveling and shaking so many hands, but ultimately it is worth it if I do it in a thoughtful and logical way.

In-person experiences are valuable, but I still feel that consistent, smart, and a syndicated virtual experience can reach more people, and make a more significant impact. It costs a lot less that traveling and attending conferences too. A robust presence isn’t easy to setup, and takes time to establish, but once in motion it can be the most effective way to build an audience. After eight years of doing API Evangelist, with some of it exclusively operating on the road, I can say that the sustained virtual presence will have the biggest impact, and provide a much more evergreen exposure that will keep on producing results even when you aren’t working. I can take a week off like I just did, and my traffic numbers keep growing, as long as I do not take too much time off, and neglect my work for more than a week or two–even when I took 3 months off a while back, my numbers and presence wasn’t damaged to badly.

In the end, it is all a balance. After a road trip I’m always happy to be home, and feel like I want to say no to other invitations. I feel like I could do so much more if I just had interrupted time at home doing the work I feel matters. While this is true to some degree, I definitely grow and learn a lot by talking with people at companies, organizations, institutions, and government agencies, as well as connecting at the right conferences and Meetups. It is a balance I have to assess from month to month, and have to put serious thought into which events and in-person engagements will make a difference. It is something I don’t think there is a perfect formula for, and is something that evolves, flows, and sometimes dries up depending on the season. It is something I just have to keep trusting my gut, while also forcing myself out of my comfort zone as much as I can possibly handle.

My Response To The VA Microconsulting Work Statement On API Outreach

The Department of Veterans Affairs (VA) is listening to my advice around how to execute their API strategy and adopting a micro-approach to not just delivering services, but also to the business of moving the platform forward at the federal agency. I’ve responded to round one, and round two of the RFI’s, and now they have submitted a handful of work statements on Github, so I wanted to provide an official response, share my thoughts on each of the work statements, and actually bid for the work.

First, Here is The VA Background The Lighthouse program is moving VA towards an Application Programming Interface (API) first driven digital enterprise, which will establish the next generation open management platform for Veterans and accelerate transformation in VA’s core functions, such as Health, Benefits, Burial and Memorials. This platform will be a system for designing, developing, publishing, operating, monitoring, analyzing, iterating and optimizing VA’s API ecosystem.

Next, What The VA Considers The Play As the Lighthouse Product Owner, I must have a repeatable process to communicate with internal and external stakeholders the availability of existing, new, and future APIs so that the information can be consumed for the benefit of the Veteran. This outreach/evangelism effort may be different depending on the API type.

Then, What The VA Considers The Deliverable A defined and repeatable strategy/process to evangelize existing, new, and future APIs to VA’s stakeholders as products. This may be in the form of charts, graphics, narrative, or combination thereof. Ultimately, VA wants the best format to accurately communicate the process/strategy. This strategy/process may be unique to each type of API.

Here Is My Official Response To The Statement API Evangelism is always something that is more about people, than it is about the technology, and should always be something that speaks to not just developers, being inclusive to all stakeholders involved in, and being served by a platform. Evangelism is all about striking the right balance around storytelling about what is happening across a platform, providing a perfect blend of sales and marketing that expands the reach of the platform, while also properly showcasing the technical value APIs bring to the table.

For the scope of this micro engagement around the VA API platform, I recommend focusing on delivering a handful of initiatives involved with getting the word out about what the API platforms, while also encouraging feedback, but all in an easily measurable way:

  • Blogging - No better way to get the word out than an active, informative, and relevant blog with an RSS feed that can be subscribed to.
  • Twitter - Augmenting the platform blog with a Twitter account that can help amplify platform storytelling in a way that can directly engage with users.
  • Github - Make sure the platform is publishing code, content, and other resources to Github repositories for the platform, and engaging with the Github community around these repos.
  • Newsletter - Publishing a weekly newsletter that includes blog posts, other relevant links to things happening on a platform, as well as in the wider community.
  • Feedback Loop - Aggregating, responding to, supporting, and organizing email, Twitter, Github, and other feedback from a platform and report back to stakeholders, as well as incorporate into regular storytelling.

For the scope of this project, there really isn’t room to do much else. Daily storytelling, Twitter, and Github engagement, as well as a weekly newsletter would absorb the scope of the project for a 30-60 day period. There would be no completion date for this type of work, as it is something that should go on in perpetuity. However, the number of blog posts, tweets, repos, followers, likes, subscribers, and other metrics could be tracked and reported upon weekly providing a clear definition of what work has been accomplished, and the value from the overall effort over any timeframe.

Evangelism isn’t rocket science. It just takes someone who cares about he platform’s mission, and the developers, and end-users being served by the platform. With a little passion, and technical curiosity, a platform can become alive with activity. A little search engine and social media activity can go a long way towards bringing in new users, keeping existing users engaged and encouraging increased level of activities, internally and externally around platform operations. With simple KPIs in place, and a simple reporting process in operation, the evangelism around a platform can be executed, quantified, and scaled across several individuals, as well as rolling teams of contractors.

Some Closing Thoughts On This Project That concludes my response to the work statement. Evangelism is something I know. I’ve been studying and doing it for 8 years straight. Simple, consistent, informative evangelism is why I’m in a position to respond to this project out of the VA. It is how many of these ideas have been planted at the VA, through storytelling I’ve been investing in since I worked at the VA in 2013. A single page response doesn’t allow much space to cover all the details, but an active blog, Twitter, Github, and newsletter with a structured feedback loop in place can provide the proper scaffolding needed not to just execute a single cycle of evangelism, but guide many, hopefully rolling contracts to deliver evangelism for the platform in an ongoing fashion. Hopefully bringing fresh ideas, individuals, storytelling and outreach to the platform. Which can significantly amplify awareness around the APIs being exposed by the agency, and helping the platform better deliver on the mission to better serve veterans.

An OpenAPI Vendor Extension For Defining Your API Au

The food delivery service Zalando has an interesting approach to classifying their APIs based upon who is consuming them. It isn’t just about APIs being published publicly, or privately, they actually have standardized their definition, and have established an OpenAPI vendor extension, so that the definition is machine readable and available via their OpenAPI.

According to the Zalando API design guide, “each API must be classified with respect to the intended target audience supposed to consume the API, to facilitate differentiated standards on APIs for discoverability, changeability, quality of design and documentation, as well as permission granting. We differentiate the following API audience groups with clear organisational and legal boundaries.

  • component-internal - The API consumers with this audience are restricted to applications of the same functional component (internal link). All services of a functional component are owned by specific dedicated owner and engineering team. Typical examples are APIs being used by internal helper and worker services or that support service operation.
  • business-unit-internal - The API consumers with this audience are restricted to applications of a specific product portfolio owned by the same business unit.
  • company-internal - The API consumers with this audience are restricted to applications owned by the business units of the same the company (e.g. Zalando company with Zalando SE, Zalando Payments SE & Co. KG. etc.)
  • external-partner - The API consumers with this audience are restricted to applications of business partners of the company owning the API and the company itself.
  • external-public - APIs with this audience can be accessed by anyone with Internet access.

Note: a smaller audience group is intentionally included in the wider group and thus does not need to be declared additionally. The API audience is provided as API meta information in the info-block of the Open API specification and must conform to the following specification:

#/info/x-audience: type: string x-extensible-enum: - component-internal - business-unit-internal - company-internal - external-partner - external-public description: | Intended target audience of the API. Relevant for standards around quality of design and documentation, reviews, discoverability, changeability, and permission granting.

Note: Exactly one audience per API specification is allowed. For this reason a smaller audience group is intentionally included in the wider group and thus does not need to be declared additionally. If parts of your API have a different target audience, we recommend to split API specifications along the target audience — even if this creates redundancies (rationale).

Here is an example of the OpenAPI vendor extension in action, as part of the info block:

swagger: ‘2.0’ info: x-audience: company-internal title: Parcel Helper Service API description: API for <…> version: 1.2.4

Providing a pretty interesting way of establishing the scope and reach of each API in a way that makes each API owner think deeply about who they are / should be targeting with the service. Done in a way that makes the audience focus machine readable, and available as part of it’s OpenAPI definition which can be then used across discovery, documentation, and through API governance and security.

I like the multiple views of who the audience could be, going beyond just public and private APIs. I like that it is an OpenAPI vendor extension. I like that they even have a schema crafted for the vendor extension–another interesting concept I’d like to see more of. Overall, making for a pretty compelling approach to define the reach of our APIs, and quantifying the audience we are looking to reach with each API we publish.

Axway Asking for an OpenAPI of The API So They Can Screenshot It

We are working closely with Axway on a number of projects over here at After we got out of a meeting with their team the other day we received an email from them asking if we had an OpenAPI definition for a demo market data API. They were wanting to include it in some marketing materials, and needed a screenshot of it. To be able to generate the visual they desired, they needed an OpenAPI to make it tangible enough for capturing in a screenshot and presenting as part of a larger story.

This may sound like a pretty banal thing, but when you step back and realize the importance of OPenAPI when it comes to communication, and making something very abstract a tangible, visual thing, it becomes more significant. You can tell someone there is a market data API, but taking a screenshot of documentation generated via an OpenAPI which displays the market data paths, a couple of parameters like stocker ticker symbol and maybe date range, and then plug in some actual values like the ticker symbol for AAPL, and show the JSON response takes things to a new level. This is OpenAPI empowered storytelling, marketing and communications in my book. Elevating what OpenAPI brings to the table to new stops along the API life cycle.

This isn’t just about documentation. This is about making an abstract API concept more visual, more meaningful, and able to be captured in an image. Axway is trying to demonstrate the value of their API solutions, coupled potentially with services, in a single image–providing a lot more rich context, and visualizations that amplify their marketing materials. This isn’t just documenting what is going on so that developers know what to do with an API, this is telling stories so that business users understanding what is possible with an API–using a machine readable format like OpenAPI to help deliver the 1000 words the image will be worth.

Using OpenAPI like this reflects where I’d like to see API documentation go. Sure, we still need dynamic API documentation driven by OpenAPI definitions for developers to understand what is going on, but we need more snippets, visualization, and emotion driving solutions to exist. Things that marketers, bloggers, and other storytellers can use in their materials. We need OpenAPI-driven tools that help them plug in a relevant API definition, and generate a meaningful visual that they can use in a slide deck, blog post, or other material. We need our API documentation to speak beyond the developer community and become something that anyone can put to work in their API storytelling efforts–no coding required.

Having A Developer.[YourDomain] Is Clear Differentiator In The API Game

I am profiling US, UK, French, and German banks as part of some research I am doing for I am profiling how far along in the API journey these banks are, and one clear differentiator for me is whether a bank has a developer.[bankdomain] subdomain setup for their APIs or not. The banks that have a dedicated subdomain for their API operations have a clear lead over those who do not. The domain doesn’t do much all by itself, but it is clear that when a bank can get this decision made, many of the other decisions that need to be made are also happening in tandem.

This isn’t unique just to banking. This is something I’ve written about several times over the years, and remains constant after looking at thousands of APIs over the last eight years. When a company’s API presence exists within the help section of their website, the API is almost always secondary to the core business. When a company relies on a 3rd party service for their API and developer presence, it almost always goes dormant after a couple months, showing that APIs are just not a priority within the company. Having a dedicated subdomain, landing page, and set of resources dedicated to doing APIs goes a long way towards ensuring an API program gains the momentum it needs to be successful within an organization, and industry.

I know that having a dedicated subdomain for API operations seems like a small thing to many folks. However, it is one of the top symptoms of a successful API in my experience. Making data, content, and algorithms available in a machine readable way for use in other applications by 3rd party via the web is something every company, organization, institution, and government agency should be doing in 2018. It is the next iteration of the web, and is not something that should be a side project. Having a dedicated subdomain demonstrates that you understand this, and an API won’t just be the latest trend at your organization. Even if your APIs are entirely private in the beginning, having a public portal for your employees, partners, and other stakeholders will go along way towards helping you get the traction you are looking for in the API game.

How API Evangelist Works

I’ve covered this topic several times before, but I figured I’d share again for folks who might have just become readers int he last year. Providing an overview of how API Evangelist works, to help eliminate confusion as you are navigating around my site, as well as to help you find what you are looking for. First, API Evangelist was started in the summer of 2010 as a research site to help me better understand what is going on in the world of APIs. In 2017, it is still a research site, but it has grown and expanded pretty dramatically into a network of websites, driven by a data and a content core.

The most import thing to remember is that all my sites run on Github, which is my workbench in the the API Evangelist workshop. is the front door of the workshop, with each area of my research existing as its own Github repository, at its own subdomain with the apievangelist domain. An example of this can be found in my API design research, where you will find at As I do my work each day, I publish my research to each of my domains, in the form of YAML data for one of these areas:

  • Organizatons - Companies, organizations, institutions, programs, and government agencies doing anything interesting with APIs.
  • Individuals - The individual people at organizations, or independently doing anything interesting with APIs.
  • News - The interesting API related, or other news I curate and tag daily in my feed reader or as I browse the web.
  • Tools - The open source tooling I come across that I think is relevant to the API space in some way.
  • Building Blocks - The common building blocks I find across the organizations, and tooling I’m studying, showing the good and the bad of doing APIs.
  • Patents - The API related patents I harvest from the US Patent Office, showing how IP is impacting the world of APIs.

You can find the data for each of my research areas in the _ data folder for each repository. Which is then rendered as HTML for each subdomain using Liquid via each Jekyll CMS driven website. All of this is research. It isn’t meant to be perfect, or a comprehensive directory for others to use. If you find value in it–great!! However, it is just my research laying on my workbench. It will change, evolve, and be remixed and reworked as I see fit, to support my view of the API sector. You are always welcome to learn from this research, or even fork and reuse it in your own work. You are also welcome to submit pull requests to add or update content that you come across about your organization or open source tool.

The thing to remember about API Evangelist is it exist primarily for me. It is about me learning. I take what I learn and publish as blog posts to API Evangelist. This is how I work through what I’m discovering as part of my research each day, and use as a vehicle to move my understanding of APIs forward. This is where it starts getting real. After seven years of doing this I am reaching 4K to 7K page views per day, and clearly other folks find value in reading, and sifting through my research. Because of this I have four partners, 3Scale, Restlet, Runscope, and Tyk who pay me money to have their logo on the home page, in the navigation, and via a footer toolbar. Runscope also pays me to place a re-marketing tag on my site so they can show advertising to my users on other websites, and Facebook. This is how I pay my rent, an how I eat each month.

Beyond this base, I take my research and create API Evangelist industry guides. API Definitions, and API Design are the two most recent editions. I’m currently working on one for data, database, as well as deployment, and management. These guides are sometimes underwritten by my partners, but mostly they are just the end result of my API research. I also spend time and energy taking what I know and craft API strategy and white papers for clients, and occasionally I actually create APIs for people–mostly in the realm of human services, or other social good efforts. I’m not really interested in building APIs for startups, or in service of the Silicon Valley machine. Even tough I enjoy watching, studying, and learning from this world, because there are endless lessons regarding how we can use technology in this community, as well as how we should not be using technology.

That is a pretty basic walk through of API Evangelist works. It is important to remember I am doing this research for myself. To learn, and to make a living. API Evangelist is a production, a persona I created to help me wade through the technology, business, and politics of APIs. It reflects who I am, but honestly is increasingly more bullshit than it is reality, kind of like the API space. I hope you enjoy this work. I enjoy hearing from my readers, and hearing how my research impacts your world. It keeps me learning each day, and from ever having to go get a real job. It is always a work in progress and never done. Which I know frustrates some, but I find endlessly interesting, and is something that reflects the API journey, something you have to get used to if you are going to be successful doing APIs in this crazy world.

Sharing Top Sections From Your API Documentation As Part Of Your Communications Strategy

I’m always learning from the API communication practices from out of the different AWS teams. From the regular storytelling coming out of the Alexa team, to the mythical tales of leadership at AWS that have contributed to the platform’s success, the platform provides a wealth of examples that other API providers can emulate.

As I talked about last week, finding creative ways to keep publishing interesting content to your blog as part of your API evangelism and communications strategy is hard. It is something you have to work at. One way I find inspiration is by watching the API leaders, and learning from what they do. An interesting example I recently found out of the AWS security team, was their approach to showcasing the top 20 AWS IAM documentation pages so far in 2017. It is a pretty simple, yet valuable way to deliver some content for your readers, that can also help you expose the dark corners of your API documentation, and other resources on your blog.

The approach from the AWS security team is a great way to generate content without having to come up with good ideas, but also will help with your SEO, especially if you can cross publish, or promote through other channels. It’s pretty basic content stuff, that helps with your overall SEO, and if you play it right, you could also get some SMM juice by tweeting out the store, as well as maybe a handful of the top links from your list. It is pretty listicle type stuff, but honestly if you do right, it will also deliver value. These are the top answers, in a specific category, that your API consumers are looking for answers in. Helping these answers rise to the top of your blog, search engine, and social media does your consumers good, as well as your platform.

One more tool for the API communications and evangelism toolbox. Something you can pull out when you don’t have any storytelling mojo. Which is something you will need on a regular basis as an API provider, or service provider. It is one of the tricks of trade that will keep your blog flowing, you readers reading, and hopefully your valuable API, products, services, and stories floating to the top of the heap. And that is what all of this is about–staying on top of the pile, keeping things relevant, valuable, and useful. If we can’t do that, it is time to go find something else to do.

Sharing Top Sections From Your Api Documentation As Part Of Your Communications Strategy

404: Not Found

Developing The Ability To Repeat The Same API Stories Over And Over

After seven years of telling stories on API Evangelist I’ve had to repeat myself from time to time. Honestly, I repeat myself A LOT. Hopefully I do it in a way that some of you don’t notice, or at least you are good at filtering the stories you’ve already heard from your feed timeline. My primary target audience is the waves of new folks to the world of APIs I catch with the SEO net I’m casting and working on a daily basis. Secondarily, it is the API echo chamber, and folks who have been following me for a while. I try to write stories across the spectrum, speaking to the leading edge API conversations, as well as the 101 level, and everything in between.

Ask anyone doing API evangelism, advocacy, training, outreach, and leadership–and they’ll that you have to repeat yourself a lot. It is something you get pretty sick of, and if you don’t find ways to make things interesting, and change things up, you will burn out. To help tell the same story over and over I’m always looking for a slightly different angle. Let’s take API Meetups as an example. Writing a story about conducting an API Meetup has been done. Overdone. To write a new story about it I’ll evaluate what is happening at the Meetup that is different, or maybe the company, or the speaker. Diving into the background of what they are doing looking for interesting things they’ve done. You have to find an angle to wrap the boring in something of value.

API documentation is another topic I cover over, and over, and over. You can only talk about static or interactive API documentation so much. Then you move into the process behind. Maybe a list of other supporting elements like code samples, visualizations, or authentication. How was the onboarding process improved? How the open source solution behind it simplifies the process. You really have to work at this stuff. You have to explore, scratch, dig through your intended topic until you find an angle that you truly care about. Sure, it has to matter to your readers, but if you don’t care about it, the chances of writing an interesting story diminishes.

This process requires you to get to know a topic. Read other people’s writing on the topic. Study it. Spin it around. Dive into other angles like the company or people behind. Spend time learning the history of how we got here with the topic. If you do all this work, there is a greater chance you will be able to find some new angle that will be interesting. Also, when something new happens in any topical area, you have this wealth of knowledge about it, and you might find a new spark here as well. Even after all that, you still might not find what you are looking for. You still end up with many half finished stories in your notebook. It is just the way things go. It’s ok. Not everything you write has to see the light of day. Sometimes it will just be exercise for the next round of inspiration. That hard work you are experiencing to find a good story is what it takes to reach the point where you are able to discover the gems, those stories that people read, retweet, and talk about.

Tyk Is Conducting API Surgery Meetups

I was having one of my regular calls with the Tyk team as part of our partnership, discussing what they are up to these days. I’m always looking to understand their road map, and see where I can discover any stories to tell about what they are up to. A part of their strategy to build awarness around their API management solution that I found was interesting, was the API Surgery event they held in Singapore last month, where they brought together API providers, developers, and architects to learn more about how Tyk can help them out in their operations.

API surgery seems like an interesting evolution in the Meetup formula. They have a lot of the same elements as a regular Meetup like making sure there was pizza and drinks, but instead of presentations, they ask folks to bring their APIs along, and they walk them through setting up Tyk, and deliver an API management layer for their API operations. If they don’t have their own API, no problem. Tyk makes sure there are test APIs for them to use while learning about how things work. Helping them understand how to deliver API developer onboarding, documentation, authentication, rate limiting, monitoring, analytics, and the other features that Tyk delivers.

They had about 12 people show up to the event, with a handful of business users, as well as some student developers. They even got a couple of new clients from the event. It seems like a good way to not beat around the bush about what an API service provider is wanting from event attendees, and getting down to the business at hand, learning how to secure and manage your API. I think the Meetup format still works for API providers, and service providers looking to reach an audience, but I like hearing about evolutions in the concept, and doing things that might bring out a different type of audience, and cut out some of the same tactics we’ve seen play out over the last decade.

I could see Meetups like this working well at this scale. You don’t need to attract large audiences with this approach. You just need a handful of interested people, looking to learn about your solution, and understand how it solves a problem they have. Tyk doesn’t have to play games about why they are putting on the event, and people get the focus time with a single API service provider. Programming language meetups still make sense, but I think as the API sector continues to expand that API service provider, or even API provider focused gatherings can also make sense. I’m going to keep an eye on what Tyk is doing, and look for other examples of Meetups like this. It might reflect some positive changes out there on the landscape.

Disclosure: Tyk is an API Evangelist partner.

How Do We Help Folks Understand That APIs Are A Journey?

I was hanging out with my friend Mike Amundsen (@mamund) in Colorado last month and we ended up discussing folks uncertainty with APIs. You see, many folks that he has been talking to were extremely nervous about all the unknowns in the world of APIs, and were looking for more direction regarding what they should be doing (or not doing). Not all people thrive in a world of unknown unknowns, and not even in a world of known unknowns. Many just want a world of known knowns. This is something that makes the API landscape a very scary thing to some folk, and world where they will not thrive and be successful unless we can all begin to find a way to help them understand that this is all a journey.

I love figuring all of this API stuff out, and I know Mike does too. We like thinking about the lofty concepts, as well as figuring out how to piece all the technical elements together in ways that work in a variety of business sectors. Many folks we are pushing APIs on aren’t like us, and just want to be told what to do. They just want the technology solution to their problem. A template. A working blueprint. It freaks them out to have so many options, possibilities, patterns, and directions they take things. I feel like we are setting folks up for failure when we talk them into embarking on an API journey without the proper training, equipment, support, and guidance.

I think about the last seven years doing this, and how much I’ve learned. Realizing this makes me want to keep doing APIs, just so I can keep learning new things. I thought I understood REST when I started. I didn’t. I thought I understand the web when I started, I didn’t (still don’t). I was missing a lot of the basics, and no matter what folks told me, or how precise their language was, I still needed to bang my head on something over and over before I got it. I was missing a significant amount of why hypermedia can be a good approach without truly understanding content negotiation, and link relations. Realizing how much I still need to explore and learn has only emboldened me on my journey, but I’m not convinced this will be the case with everyone. We are wrong to assume everyone is like us.

As technologists and autodidacts we often overestimate our own ability, as well as what others are capable of. We realize APIs are not a destination, but a journey. However, we suck at explaining this to others. We are horrible at understanding all of the stepping stones that got us here, and recreating them for others. I put myself into this group. I think about this stuff full time, and I still regularly stumble when it comes to on-boarding folks with what API are, and properly helping them in their journey. I still do not have a proper set of on-boarding lessons for folks, beyond my API 101 stuff. I talk a lot of talk about the API life cycle, the API economy, and all the business and politics of APIs, but I still can’t point folks to where the yellow brick road is. We have to get better at this if we expect folks to ever catch up.

This is one reason I feel Zapier, and other iPaaS providers are so important. We should be helping people understand APIs and integration in context of the problems they are trying to solve, not in terms of REST, SDKs, or any of the other technical jargon we spew. With Zapier, folks can play with Zaps (recipes) that deliver meaningful API integration that actually solve a problem in their world. They can play with what is possible, without learning all the technical pieces first. They can evolve in their business world, while also progressing on their API journey. IDK. I’m just trying to find ways to help folks better understand what APIs are. I’ll never make everything known to them, but I’m hoping that I can help make folks a little less nervous about the known unknowns, and who knows maybe some day they’ll feel brave enough, and confident in their API awareness that they’ll be able to operate in a world of the unknown unknowns, and settle in on the perpetual journey that are APIs.

Concerns Around Working With The API Evangelist At Large Organizations

I know that I make some tech companies nervous. They see me as being unpredictable, with no guarantees regarding what I will say, in a world where the message should be tightly controlled. I feel it in the silence from many of the folks that are paying attention to me at large companies, and I’ve heard it specifically from some of my friends who aren’t concerned with telling me personally. These concerns keep them from working with me on storytelling projects, and prevent them from telling me stories about what is happening internally behind their firewall. It often doesn’t stop employees from telling me things off the record, but it does hinder official relationships, and on the record stories from being shared.

I just want folks to know that I’m not in the scoop, or gotcha business. I only check-in on my page views monthly to help articulate where things are with my sponsors. I’m more than happy to keep conversations off the record, anonymize sources and topics. Even the folks in the space who have pissed me off do not get directly called out by me. Well, most of them. I’ve gone after Oracle a couple of times, but they are the worst of the worst. There are other startups and bigcos who I do not like, and you don’t ever hear me talking trash about them on my blog. Most of my rants are anonymized, generalized, and I take extra care to ensure no enterprise egos, careers, or brands are hurt in the making of API Evangelist.

If you study my work, you’ll see that I talk regularly with federal government agencies, and large enterprise organizations weekly, and I never disclose things I shouldn’t be. If you find me unpredictable, I’m guessing you really haven’t been tuning into what I’ve been doing for very long, or your insecurities run deeper than anything to do with me. I’m not in the business of making folks look bad. Most of the companies who are looking bad in the API space do not need my help, they excel at doing it on their own. I’m usually just chiming in to help amplify, and use as a case study for what API providers should consider NOT DOING in their own API operations. Sure, I may call you out for your dumb patents, and the harmful acquisitions you make, but anything I rant about is going to already be public material–I NEVER do this with private conversations.

So, if you are experiencing reservations about sharing stories with me, or possibly sponsoring some storytelling on API Evangelist because you are worried about what will happen, stop fretting. If you are upfront with me, clear about what is on the record, and what is off, and honest about what you are looking to get out of the relationship, things will be fine. Even if they end up being rocky, I’m not the kind of person to call you out on the blog. I may complain, rant, and vent, but you can look through seven years of the blog and you won’t find me doing that about anyone I’ve specifically worked with on storytelling projects. I don’t always agree with why corporations, institutions, and government agencies are so controlling of the message around their API operations, but I will be respectful of any line you draw for me.

I Am Not A Card Carrying Restafarian I Just Believe In The Web

I am always surprised at the folks who I meet for the first time who automatically assume I’m all about the REST. It is always something that is more telling about the way they see the world (or don’t), than it ever is about me as THE API Evangelist. It is easy to think I’m going to get all RESTY, and start quoting Roy, but I’m no card carrying RESTafarian, like my buddy Darrel Miller (@darrel_miller) (not that is what Darrel does ;-). Really the only thing I get passionate about is making sure we are reusing the web, and I am pretty much be a sellout on almost everything else.

I am just looking to understand how folks are exposing interfaces for their digital resources using the web, making them available for use in other applications. I feel like RESTful approaches are always a good start for folks to begin considering, and learning from when beginning their journey, but I’m rarely going to get all dogmatic about REST. There are trade-offs with any approach you take to providing programmatic interfaces using the web, and you should understand what these are whether your are using REST, Hypermedia, (g)RPC, GraphQL, or any other number of protocols and technologies available out there. A RESTful approach using the web just tends to be the lowest common denominator, the cheapest, and widest reaching solution we have on the table. Rarely is it ever the perfect solution–there are no such things. #sorry

If you are entering into discussions with me thinking I’m 100% team REST, you are mistaken, and you have profiled yourself considerably for me. It shows me that you haven’t done a lot of (wide) reading on the subject of APIs, and while you may be an expert, you probably are a very siloed expert who doesn’t entertain a lot of outside opinions, and keep an eye on how the space is shifting and changing. When I encounter folks like you in the space you’ll often find me pretty quiet, submissive, and just nodding my head a lot. As you aren’t my target audience, and there isn’t much I can say that will shift your world view. Your opinions are pretty set, and I’m not going to be the one who moves them forward. My role is to reach folks are looking for answers, not those who already have them.

What APIs Excite Me And Fuels My Research And Writing

I am spending two days this week with the Capital One DevExchange team outside of Washington DC, and they’ve provided me with a list of questions for one of our sessions, which they will be recording for internal use. To prepare, I wanted to work through my thoughts, and make sure each of these answers were on the tip of my tongue–here is one of those questions, along with my thoughts.

The number API that gets me out of bed each day, with an opportunity to apply what I’ve learned in the API sector is with the Human Services Data API (HSDA). Which is an open API standard I am the technical lead for which helps municipalities, and human service organizations better share information that helps people find services in their communities. This begins with the basics like food, housing, and healthcare, but in recent months I’m seeing the standard get applied in disaster scenarios like Hurricane Irma to help organize shelter information. This is why I do APIs. The project is always struggling for funding, and is something I do mostly for free, with small paychecks whenever we receive grants, or find projects where we can deliver an actual API on the ground.

Next, I’d say it is government APIs at the municipal, state, but mostly at the federal levels. I was a Presidential Innovation Fellow in the Obama administration, helping federal agencies publish their open data assets, take inventory of their web services. I don’t work for the government anymore, but it doesn’t mean the work hasn’t stopped. I’m regularly working on projects to ensure RFPs, and RFIs have appropriate API language in them, and talking with agencies about their API strategy, helping educate them what is going on in the private sector, and often times even across other government agencies. APIs like the new FOIA API, Recreational Information Database API,, IRS APis, and others will have the biggest impact on our economy and our lives in my opinion, so I make sure to invest a considerable amount of time here whenever I can.

After that, working with API education and awareness at higher educational institutions is one my passions and interest. My partner in crime Audrey Watters has a site called Hack Education, where she covers how technology is applied in education, so I find my work often overlapping with her efforts. A portion of these conversations involve APIs at the institutional level, and working with campus IT, but mostly it about how the Facebook, Twitter, WordPress, Dropbox, Google, and other public APIs can be used in the classroom. My partner and I are dedicated to understanding the privacy implications of technology, and how APIs can be leveraged to give students and faculty more control over their data and content. We work regularly to tell stories, give talks, and conduct workshops that help folks understand what is possible at the intersection of APIs and education.

After that, I’d say the main stream API sector keeps me interested. I’m not that interested in the whole startup game, but I do find a significant amount of inspiration from studying the API pioneers like SalesForce and Amazon, and social platforms like Twitter and Facebook. As well as the cool kids like Twilio, Stripe, and Slack. I enjoy learning from these API leaders, studying their approaches, but where I find the most value is sharing these stories with folks in SMB, SME, and the enterprise. These are the real-world stories I thrive on, and enjoy retelling as part of my work on API Evangelist. I’m a technologist, so the technology of doing APIs can be compelling, and the business of doing this has some interesting aspects, but it’s mostly the politics of doing APIs that intrigues me. This primarily involves the politics of the humans involved within a company, or industry, providing what I always find to be the biggest challenges of doing APIs.

In all of these areas, what actually gets me up each day, is being able to tell stories. I’ve written about 3,000 blog posts on API Evangelist in seven years. I work to publish 3-5 posts each weekday, with some gaps in there due to life getting in the way. I enjoy writing about what I’m learning each day, showcasing the healthy practices I find in my research, and calling out the unhealthy practices I regularly come across. This is one of the reasons I find it so hard to take a regular job in the space, as most companies are looking to impose restrictions, or editorial control over my storytelling. This is something that would lead to me not really wanting to get up each day, and is the number one reason I don’t work in government, resulting in me pushing to make change from the outside-in. Storytelling is the most important tool in my toolbox, and it should be in every API providers as well.

If you think there is a link I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.