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 :
capabilities (offered as APIs),
relevant to the partner?
know about the existence
of your API Store?
the partner to discover and
understand your APIs?
the partner to play with
your API Sandbox?
partner purchase and get
on-boarded with your APIs?
the developer to generate client
code for plug-and play integration?
and visualize API
consumption with ease?
APIs perform in terms
of functionality and speed?
revenue-share and other
monetizable elements addressed?
the developers to switch
across API versions?
engage seamlessly for issue
reporting, feature requests, etc.?
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
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
DigitMarketTM 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
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
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:
- Stability of the API in-terms of adherence to operational SLAs such as uptime, responsiveness, error rates, etc.
- Ability of the developer to easily engage with the API operations team to report issues, raise incidence tickets, get resolution updates, etc.
- Notifying all developers of the API interface/functionality changes and working with them to migrate from one API version to another.
- Co-ordinating with developers to announce and manage planned downtimes
- 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.
- 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
 |
- Set a robust API strategy that covers the integration of all your key IT assets and data
- Design and develop APIs with clear objectives for each
- Efficiently orchestrate API lifecycles while tracking API calls and API monetisation
Related Posts
In 2008, a significant outage in its data center prevented Netflix from sending DVDs to its customers for three days which prompted the company to rethink its IT architecture.
Organizations today are confronted with challenges arising from the growing number of applications and managing the volume of data being generated across cloud and on-premise environments.
Today, as business data increasingly proliferates a multitude of systems, app-integration teams are finding it increasingly difficult to keep pace. While a platform-based approach takes the pain out of integrating and scaling applications, the volume, velocity, and veracity of data are adding to integration complexities.
Whitepaper
Analyst Speak
(THIS) has been cited among notable vendors by Forrester Research in its report ‘The API Management Software Landscape, Q1 2024’. The report recognizes Torry Harris as a provider offering API management solutions with a geographic focus in the EMEA & APAC regions.
Forrester observes that the initial rush to “lift and shift” to the cloud has now been replaced by a focus on modernization and digital transformation. Cloud migration is the first step in a long journey to take advantage of the latest cloud-native technologies and services.
Torry Harris is a 'Strong Performer' in The Q3 2022 Forrester Wave™ for API Management Solutions. This report shows how each provider measures up and helps technology architecture and delivery (TAD) professionals select the right one for their needs.
Past Webinars
