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

API Sandbox: API Developer Best Practices

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: API Development Best Practices

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

Frictionless API In-life Operations: API Management Best Practices

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

Related Posts

Change management, cultural fitment, and best practices for setting up a Global Capability Center

In an era of increased globalization, businesses are actively seeking opportunities beyond their local markets to access a diverse global talent pool.

What to Look for in an iPaaS Vendor - The Top Five Criteria

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.

Overcoming Key Integration Platform-as-a-Service Implementation Challenges

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.


Whitepaper - Migrating to a hybrid integration platform (HIP) makes your cloud journey easy
Digital transformations tend to focus on the desired high-level benefits such as greater efficiency and profitability, more operational and business agility, and better customer experience.
Whitepaper - Why Governance is the key to ROI in Digital Transformation
It turns out that a major common contributor of almost all transformation flops is poor governance. Digital transformation involves every aspect of an organization and everyone in it. Structured governance is essential to ensure that everyone takes the same approach to common goals, in a coordinated, timely way.
Whitepaper - 7 Steps to Successful RPA Implementation
Intelligent Automation is boosted by the growing demand to digitize and automate business processes at a time when the Covid-19 pandemic requires rapid workplace transformation.

Analyst Speak

THIS recognized as a notable vendor by Forrester in its 2024 report on the API Management Software Landscape.

(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 cites Torry Harris- Vendor analysis for application modernization and migration services

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 Forrester Wave™ for API management solutions

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

On-demand webinar
Empowering your SME customers for the new DIGITAL normal: role of APIs and Microservices in the current climate
SMEs in particular, hard hit by physical constraints, acutely need to be digitally connected and empowered towards identifying sales and service opportunities.
On-demand webinar
Microservices Governance: Best practices for CSPs
A well-thought-out governance approach can help offset the costs of implementing Microservices and deliver higher benefits from your investments.
On-demand webinar
Practical use-cases to monetise Open Banking APIs
In this webinar, Thomas Zink – IDC research director for European financial services talked about the revenue potential of API enabled use-cases and how to overcome barriers to adoption.