Harold Wiegers and I bring years of experience designing and building API programs with talented colleagues and leaders in various industries. We’ve worked with organizations from telecommunications, marketplace (Platform as a Service–PaaS), and eCommerce to global distribution.
There are several ways to garner internal and external support for API adoption and success. Start with the kind of experience you want to build an end to end and then gauge a realistic starting point to iterate on until you get there.
Design your API specification as the core of the work of the API teams and use the portal to inspire and facilitate engagement. Internally and externally, do API consumers and supporters understand what the API does and what role does the portal plays in educating them?
The key to success is the culture (mindset) around an API
API culture always starts inside the company as Darrin Weber, Architect at Air Products, describes how they used their API portal to produce unexpected internal innovation. For example, what are the ways that you engage employees with your API practice today? Details about Darrin’s practice culture are below.
Harold says “many enterprises have embraced the API portal as their central innovation hub” with APIs as the “innovation network which becomes the famous lego blocks which build new solutions for companies to drive customer experience.”
He also sees customers using the API portal as part of a security requirement. For example, the API portal keeps API keys that, along with any password, should not be emailed. Self-service is also a major developer experience DX driver for a well-thought-out portal requirement.
Meetesh Patel, Sr. Director of Axway’s North American Technical Success Team, taught me about the Jobs-to-be-Done concept. When we apply the Jobs-to-be-Done theory we can ask ourselves, “What job can someone get done using an API Portal?” Your API Portal is an interactive digital brochure and window into your business answering questions such as:
Engagement
- Should I do business with you? If yes/no, Why?
- Should I work for you? If yes/no, Why?
Adoption and risk
- What are your essential offerings?
- What can I build?
- How does your API enhance my offering?
Reliability and longevity
Life cycle and community also matter: What kind of long-term support is there to make me choose to integrate with your API over others?
Performance
What is the entire end-to-end experience of your API program as experienced through your API Portal and how does it empower me to deliver the kinds of experiences that delight my users? Digital transformation is severely hindered if a slow or unreliable API frustrates users. This Harvard Business Review article sums up the issue:
In addition to the experience with the company’s people, whether the company has an API has always been an important driver to help me decide if I want to talk further. Before accepting the initial interview with a company where I served as the Director of Web Product Marketing, I made sure they had an API and by doing so, reviewed the API through their API Portal.
With the maturity of API Portals, there comes a set of expected behaviors and needs. When you deviate from those experiences, the learning curve is higher.
To demonstrate this concept, test the experience of your API portal through a method called “API Friction Logging.” By measuring the level of friction your API and corresponding API Portal offer, you can better understand what it takes to reduce support.
API friction logging provides context since you approach the portal as an outsider and differs from documenting a software bug because you give an end-to-end description to help the organization develop empathy. The right level of friction should be designed for the desired target audience.
Developer Experience
By default, an API portal generally follows the format https://developer.domain.com or https://developers.domain.com, yet https://www.domain.com/developer can also be expected.
Since the highest user base of the portal engages by either building or consuming your API, the format is targeted towards developers.
However, I’ve been working with companies to build API programs and documenting APIs from scratch since web services (SOA) days and can describe why only providing stellar documentation is not enough. Insight can also be found in the O’Reilly book chapter “Engaging Developers to Drive Adoption.”
- The documentation needs different and clearer points of reference throughout onboarding, integration, maintenance, and scaling applications.
- In addition, socializing the API using the spec alone doesn’t invite collaboration from cross-department roles, with customers and partners, or even within one API team.
Within jobs-to-be-done JTBD thinking, the API portal or developer portal is a familiar way for developers, business development, customers, partners, product managers, technical writers, and more to house important artifacts to hit the ground running:
- Developers manage access, including their API keys and other critical integration information in the portal.
- Business development along with marketing conveys compelling reasons to engage with the organization’s data, functionality, and valuable offerings.
- Partners get the support and where applicable, showcase the fruits of their integration through the portal.
- Product managers and technical writers use the portal as the face of the API including documentation.
- Throughout the organization, internal parties across business units learn, share, and innovate using internal portions of the API Portal.
As a leader over Product, Engineering, and/or Business Development, how do you justify spending on customizing an API Portal that you’ve either built or bought when your API is not directly monetized? Let’s look at how to answer to these tough decisions.
Technology innovation requires organizations to balance keeping the lights on, building products and services to delight existing employees and customers, and quietly doing new things in better ways. How do you challenge committed resources from any of these areas?
Shop window
The API Portal as a shop window
In a discussion about how API Portals can inspire innovation, my colleague and fellow Catalyst, Brian Otten described how he explained to customers how to unlock internal enterprise API consumption.
“I used to explain this to customers using the ‘shop window’ metaphor. As each domain’s product teams start adopting an API-first strategy, they are unlocking their bit of the business’ data and enabling integration much faster through search and discovery of existing APIs… also why you need taxonomies and tagging in your portal…
In essence, you get your APIs for core business data in place and then ‘fling open the virtual shop windows’ with your portal. You design and build APIs for sharing and use a consistent pipeline to do it in order to control and govern them–period!”
Even internal only, vetted customers, partners, and external third-parties benefit from the shop window concept since they have a place to use your solution and for certain APIs even if they are only internal. And if your internal community is empowered, just imagine how much better they can serve your customers.
Welcome signs for vetted communities
The API Portal as welcome signs for vetted communities
When I worked as the Community Engagement Manager for uShip’s API Program, we focused on improving our partner onboarding experience. We were building a community from scratch and typical integrators were as large as eBay motors and as small as a founder who hired third-party developers to create native mobile apps to be a more active, competitive part of the logistics marketplace platform. Though we kept up a “welcome sign” with the tagline “Ship code and tap into the global shipping market,” since we did not let just anyone sign up to use the API, we needed to showcase a way for parties to examine us and a process to do so.
Another welcome sign is a clear path to trial and adoption using sandboxes. You can test-drive Dun & Bradstreet’s API with clear upfront expectations. In a typical agile sprint, product managers and their teams may use one research spike to determine whether they want to invest in your API. Is there a way to do this today?
In fact, most enterprise software companies have a business unit that focuses solely on creating customizations on behalf of their customers. Internally, is there a way for various parties to try the API in an environment that helps them succeed in adopting the API?
Welcome signs are key to inviting vetted communities to use your platform. When I worked at an enterprise eCommerce Platform, we envisioned being able to compete against Adobe’s Magento, BigCommerce, and Shopify. Fast forward to 2019, eCommerce Platforms, the British company that reviews online platforms in an unbiased way crowns Shopify as its top pick.
The review started in 2012 according to the link and SEO. So, it is no surprise that as I attended developer experience, API docs, and API portal conferences and awards ceremonies, I met the Shopify developer who demonstrated go-to-market and platform adoption by working with the platform users.
“To launch the best developer products, your product team needs to work closely with your DevRel/DevEx team and your platform users, says Shopify’s developer experience lead Shayne Parmelee. In his talk, from DevXCon San Francisco 2018, Shayne explores the ways in which links between technical design, internal testing and user feedback make a successful go-to-market experience.”
Full transcript https://devrel.net/developer-experience/how-shopify-created-an-api-go-to-market-strategy
Video of Shayne’s Talk https://www.youtube.com/watch?v=2WgcjMA0iIA
Internally vetted communities
Below are situations where vetted communities inside your company are directly affected by and dependent on your portal.
- When your primary audience inside the company are communicators, before an API is launched even internally, the specification requires an explanation.
- Productivity goes down when the portal is down. Consider when Amazon’s API Portal is down, consumers such as data scientists looking to integrate with their APIs cannot reach the documentation.
- Teams whose dependencies rely on the API team’s work are major stakeholders of the API and an API Portal is a smart way to organize metrics, engagement, operational status, and artifacts to help Engineering and DevOps thrive.
Externally vetted communities
API Portals famous for their engagement gain the respect of global communities. If you already have a vibrant community and API Portal and want to understand better ways to position and grow both, then take a look at “Content Strategy for DevPortals” featured in the Developer Portal Awards and delivered in London. We cover five different types of developer journeys and how to support them.
Summary
API portals give APIs a home, whether you’re only looking for internal users to reach them. Since APIs are the medium to build great experiences, the portal design, when set to inspire, models great experiences for those consuming them.
Offering tangible shop windows and welcome signs of business users and anyone looking at your API to decide if it’s right for them encourages adoption. A welcome community, then is the key to a healthy and thriving API ecosystem, especially if you’re looking to attract platform adoption. We see this adoption shift enterprise software through the interaction of open source communities who not only monetized their inventions but also created a great place for technology to live.
Hear Darrin Weber, Architect at Air Products for an inside look at how they are using their API Portal to produce unexpected internal innovation.
Want to learn more? Listen to the webinar: API Portal–A foundation for unexpected innovation.
In this webinar, you will learn how to:
- Develop new channels of interactivity
- Measure API productivity
- Innovate in integrating legacy systems with cloud services.
Engage on community.axway.com, via Slack or on Twitter for more engaging and insightful ideas for your API Portal and Community.
Follow us on social