Bridging the gap between API design and development

Bridging the gap between API design and development

The design journey of building an API platform – ensuring collaborative API design, superior developer experience and accelerated customer adoption

“APIs are the connective tissue in today’s ecosystems.
For companies who know how to implement them, they can cut
costs, improve efficiency, and help the bottom line.”

McKinsey State of API,2019

But Still

Success of API is far from reality

This is mainly happening due to the ‘inside-out’ approach of building APIs, which does not focus on customer centricity

5 Different tools are required to develop APIs, leading to usability issues

Non-standardization is one of the top API technology challenges

And some more…

Longer time to market

A long time is taken to release APIs into the market since cross functional teams are dependent on each other

Poor communication

Lack of communication between stakeholders/cross-functional teams leads to poor API design

Lack of clarity

APIs become redundant as development roadmaps and purpose are not well-defined

Low adoption

Less adoption among developers because no context regarding API is provided to end consumer(who is again a developer)

     The Challenge in today’s API economy is that most of the organizations are often unable to differentiate between building the right APIs versus building the APIs right

At this point, it’s imperative to understand the difference between developing ‘API as a product’ and ‘API as a Solution’

API as a solution has an inside-out approach

API as a product has an outside-in approach

Design to the Rescue

Using m360 framework to address the
needs of building API as a Product

The m360 design framework advocates researching and understanding the moments that matter
the most to the customers and optimizing the product so that it becomes meaningful to the user.
This can be done by identifying who the users are, understanding their intentions and listen to their needs.


Profile, History, Behaviors


Where, When, What


Understand, Suggest, Anticipate

Mapping the Journey

Users at the center

Three types of personas were identified. To discover the motivations and frustrations of each of

the personas, the team interviewed few users from each of the target personas. Based on the

findings from user interviews, we plotted the journey of each user type.

Identifying Opportunities

After mapping the user journey and pain points, the UX team came up with a list of features/capabilities that would help users to achieve their intent. The details are given below:


This would be a place to design API products and would act as a
significant component in the Apitive studio


Creating an API is equivalent to creating a product life cycle management feature


The benefits and solutions offered by the product can be translated into business specs

Mock and Validate

After designing an API, the product managers or the architects can create a product mock and send the same to the client


Product managers, architects, developers, and testers can interact at multiple stages of API development

Engineering Hub

Share the API specs with the engineering team through a repository, and generate executable test cases from the specs

Improvised Flow

Design Challenges

Different types of information are required for different types of users. Therefore information had to be structurally aligned to make sure that user specific information is available without any difficulty.

The major challenges in attaining this goal is listed below:

  • The dashboard should give an overview of all the features for any user type and act as a one-stop-shop for performing all the activities.
  • One variant of the design needed to work well with all the users who will be accessing the product.
  • There was a need to ensure a set of edge cases were handled while designing it.
  • The grouping of information has to work across the target audience and make sense to them.

Frequency and Neccessity

The dashboard is the starting point for different types of users. We started to plot conceptual product flows for each user story. For each use-case, a detailed task flow was created to make sure the user need is satisfied. From each task flow, possible outcomes were accounted and prioritized.

Testing Early Helped Revise Faster

Developing prototypes quickly and testing them with users helped us to determine what user thinks when they interact with the product. It also gave product development visibiliy to stakeholders.

Crafting Visual Identity

Recognizable design is elemental to UX and UI adoption. Humans remember visuals more easily than texts. Therefore, for easy identification and navigation within Apitive, we have used iconography to represent features.

Visualizing APIs as Products

After a few iterations, we came up with a page for creating “API as a product”. We adopted a product-centric approach in designing this interface, where users can design, document, mock and publish API products.

Product basic information including version and actions in a snapshot

Current status of product and a group button with all possible upcoming actions

Comprehensive list of number of endpoints, models and policies associated with product


On average 3 specs published for 10 products created in platform

Faster API creation, updated documentation for each version

Increase in collaboration between cross functional teams

Improved discovery of global data models used in products