As enterprises expand their API-driven digital initiatives, a customer-centric mind-set with a focus on the “experience” element helps to attract and sustain traffic to developer portals, which are the face of an organization’s API offerings. A shift from just building a developer portal to building an end-to-end Developer Experience becomes important.

There are many factors that shape the overall developer experience. Some key factors are highlighted in this blog post.

Developer experience matters. Factors that will help your API Initiative stand out -

As an API Program leader, you need to ask yourself some fundamental questions :

How are your core
capabilities (offered as APIs),
relevant to the partner?
How will partners
know about the existence
of your API Store?
How easy is it for
the partner to discover and
understand your APIs?
How simple is it for
the partner to play with
your API Sandbox?
How quickly can your
partner purchase and get
on-boarded with your APIs?
Once on-boarded, how easy is it for
the developer to generate client
code for plug-and play integration?
Can the partner track
and visualize API
consumption with ease?
How do the purchased
APIs perform in terms
of functionality and speed?
How well are the
revenue-share and other
monetizable elements addressed?
How easy do is it for
the developers to switch
across API versions?
How can the developer
engage seamlessly for issue
reporting, feature requests, etc.?
How easily can a
developer opt out of your
API program?

A well-planned API strategy will provide answers to these questions and steer your organization towards providing a smoother, enriched developer experience. Modern API Management products, such as Digit Market API Manager, are designed to address aspects of such developer experience.

 

From our experience of running successful API programs for large enterprises, we recommend the following best practices across the top three developer portal experience influencers :

1. API Sandbox

Open Banking Platform

The term Sandbox emerged from sand pit, where kids freely play around, build castles and have fun. You should be able to offer the same ability to “play around” with your APIs, generate tokens, refer to API sample data, etc.

Providing a good Sandbox experience through self-service, goes a long way in ensuring a smooth developer experience. Lack of self-service capabilities in Sandbox will lead to lengthy email exchanges, handholding, telephone calls, or even worse, personal trips to partner/developer organizations to ease the on-boarding process. Some of the capabilities of an API Sandbox are :

  • Exclusive Play Area for each Developer
  • Automatic Provisioning and De-Provisioning of test data
  • Provide production-like data and offer production-like capabilities
  • Test Scenario anticipation and planning
  • Test Data publishing
  • Automatically generate API client stubs across popular programming languages
  • Security, Policies, etc. applicable to Sandbox
  • Easy switchover from Sandbox to Production

DigitMarket API Manager’s features fulfil these needs by offering a highly configurable and extensible Developer Portal.

API Publishers often overlook the sheer planning and discipline required to maintain a functional sandbox. For example, a developer consuming a Telco’s messaging API, expects the SMS to arrive on his phone during testing. It requires provisioning of a separate SMS Infrastructure in production environment or allocate a “Sandbox space” on the existing system. For data-centric APIs, it is important to provide intelligent stubs that have the capability to setup and tear-down data across multiple test runs that map to multiple API use cases. Tools such as AutoStub® exactly offer these capabilities that simplify the job of the API publisher team.

2. API Documentation

Open Banking Platform

API Documentation is the first touchpoint in the API consumption experience and is a primary decision influencer in signing up for commercial subscription. A developer survey conducted by ProgrammableWeb, a popular API marketplace, has rated ‘complete and accurate documentation’ as the highest factor, only next to service availability, responsiveness, performance, etc.

One of the common mistakes made by API publishers is to confuse API Interface reference documentation with a more holistic concept-oriented documentation. Reference documentation is usually automatically generated by combining annotations within API specs and tabulating the structural elements of the spec such as list of URI resources, methods, schema attributes, etc: Most popular API spec standards are Swagger (Open API Specification), API Blueprint and IO-Docs. On the other hand, holistic documentation includes carefully authored Tutorials, Developer Guides, On-boarding Videos, Example code, FAQs, etc.

Common problems with a spec-based reference documentation are :

  • They create an illusion that Reference docs are the only means of documentation
  • May not be reader-centric, as most of these are written by API developers who may not necessarily have the skills of a technical writer.
  • Lack of ownership
  • Does not explain the big picture. Concepts, API Grouping, etc.
  • Unless addressed specifically, auto-generated docs do not integrate with the site’s branding, look-and-feel.

While the importance of Reference documentation cannot be overlooked, the recommended best practice is to complement it with how-to guides, videos, tutorials, concept model, etc. A good example of holistic documentation is Twilio. Investing in skilled Technical Writers is key towards delivering professional documentation. A highly recommended external blog on Technical Writing in general and API Technical writing in particular is I’d Rather Be Writing.

3. Frictionless API In-life Operations

Open Banking Platform

The first two points focused on the journey and therefore, experience of the developer when he/she is exploring API s when building an App or Website. This point focuses on the post-launch experience, where a lot of factors and activities are involved in shaping the overall “operational” experience.

The most common operational elements are:

  1. Stability of the API in-terms of adherence to operational SLAs such as uptime, responsiveness, error rates, etc.
  2. Ability of the developer to easily engage with the API operations team to report issues, raise incidence tickets, get resolution updates, etc.
  3. Notifying all developers of the API interface/functionality changes and working with them to migrate from one API version to another.
  4. Co-ordinating with developers to announce and manage planned downtimes
  5. Financial back-office operations such as revenue share settlements, etc. Depending on the developer organization and their profile, the API provider could integrate with their billing or payment systems for seamless financial transactions.
  6. Deprecation and retirement of APIs.

While all three influencers detailed in this post are common in the API lifecycle, an important factor is to look at everything through a “customer experience” lens, to see how easy it is for the developer to engage with your API portal during their development journey. Our recommendation is to enrich self-service and align your internal IT Governance policies and practices to support the new model. The API Management product is secondary to investing your time in analyzing, optimizing and tailoring the end to end developer experience.

About the Author

Karthik T S

 

Latest Posts

November 19, 2019

Accelerate Enterprise Digital Transformation with a sound API Strategy
In order to grab a part of the action and participate in the race to form digital ecosystems, every enterprise worth its salt is involved in a transformation of some...

October 31, 2019

The Rise of Marketplace-Banking
Open-Banking was driven largely by regulations in the EU and the UK. However, policymakers in other nations like Japan, the USA, Australia, and Hong Kong have already taken notice of...

October 29, 2019

Getting Started with your API Store
Simply put, an API store is a one-stop-shop designed for API consumers and partners to explore the catalog of API solutions made available through your company. The store provides a...