We’re living in an era where information is driving extreme value, and companies are increasingly looking at new ways to facilitate better intercommunication of data between internal applications, as well as open up their data reserves to enter the platform economy.

According to a report published by Accenture in 2016, 81% of executives say platform-based business models will be core to their growth strategy within three years. APIs are key to this new era of digital transformation. APIs are consumed by developers of various industries with different needs, and are under constant pressure to grow and evolve their services as the company and market matures.

With such a dynamic between consumer needs and market dynamics, it’s clear APIs can no longer be treated as regular tech artifacts, and instead should be treated with the same attention and planning as any first-class product. This is why a product management approach is important to harness the true potential of an API offering and offer a compelling service which internal and external developers can’t live without.

In order to develop a product-driven, consumer-centric approach, we’ve developed a simple framework for thinking about your entire API development and delivery. Each of these steps probably deserves its own article, and I’ve shared a few additional resources when detailing these steps that can help in your journey of building an amazing API.

Step 1: Understand Your API’s purpose

What problem does your API offering promise to solve? Having an outcome-driven approach to API development can help you define better metrics of success, build a sustainable and scalable development strategy, and facilitate faster stakeholder buy-in. Some famous use-cases for APIs include:

  • Facilitating faster development and creating an adaptable architecture by exposing all internal services via APIs – Amazon
  • Creating a successful platform to drive higher engagement of users – Facebook
  • Grow traffic to main website by incentivizing sending users through a partner API model – eBay

It’s important to fully understand the purpose of your API to see how it maps into your business taxonomy. This taxonomy is composed of smaller building blocks of your business from a functional stance. Identifying this, and defining the problem space of your API, helps provide a more focused approach to conceptualizing the exact purpose of your API, and how it maps into your existing business.

Step 2: Understand Your API’s Audience

It’s easy to throw the word “developer” around. What’s important to understand is what outcome the end developer is trying to achieve, and what domain they are in. There can be two consumers for your APIs:

  • Consumers in your direct vertical: This type of API consumer builds services that directly benefit the main consumer of your core product.

For example, Slack’s end users are people within a company trying to communicate better with each other. To better facilitate collaboration and communication, Slack’s API can easily integrate with many popular third party tools that companies use and centralize notifications received from these tools. This way, Slack’s API can directly benefit the same people who use their tools and drive higher engagement and value.

  • Consumers in tangential verticals: This type of API consumer would build services that may not necessarily help the direct consumer of the product, but solves the need of another vertical.

For example, ride sharing companies like Uber could integrate with the Yelp API to give suggestions for good restaurants depending on the location their passengers are driving through. This is a classic example where Yelp’s API is benefitting the consumers of Uber, a company that can’t necessarily be considered as Yelp’s direct consumer. In general, this allows you to have the vision of your full API value chain, made up of your API’s direct and indirect consumers.

Step 3: Align your Team

A successful, scalable API program first needs a solid team behind it that’s fully aware of the API’s objectives and purpose. A great team starts with alignment. The belief that APIs are products, that they solve problems, and they have customers who care about quality, is a mindset that needs to be instilled among all of your teams. A culture of digital transformation involves full buy-in on the power of APIs to be the foundation of a successful platform.

Alignment can come when you clearly articulate the current and future state of your APIs, and how they tie into your entire business strategy. After this, figure out how you tie all of your development, operations, and marketing teams together though well-defined processes.

The way you choose the right people, and define processes that keep them and their workflow intact, can be a determining factor in the success of your API programs. You should also implement tooling that supports a collaborative approach to API development.

Step 4: Develop your API Incrementally

Having a product driven approach involves building APIs that provide immense value to your consumers. A proven tactic to delivering APIs that people love is the build-measure-learn philosophy. This is taken directly from the Lean Startup methodology of having a set of assumptions around the validity of your offering, and iteratively proving and disproving these assumptions. APIs are built incrementally, with regular stakeholder and customer feedback in every iteration, to eventually deliver a great API.

We can divide development into all of its individual life-cycle phases. It’s to be noted that all of these phases should be supported by good tooling infrastructure that align with your company’s culture, methodologies and practices. Tools like SwaggerHub, Apiary and Reprezen can help development teams design and build APIs in a collaborative environment.

Designing the API

At the end of the day, your API is just a contract between a server and client, with the request-response cycle acting as the terms of the contact. If your end consumers are the ones finding value from your API, this contract needs to be designed with their needs in mind. Designing an API means providing an effective interface that helps your internal stakeholders aligned on the API’s request-response cycles, and external consumers better understand, use, and integrate with the API.

Design is the step before you develop your technological artifacts and business logic. The design of the API acts as the forcing function to really put your API objectives and persona targeting into a human and machine-readable document for your executives and technical teams to consume. As a product management technique, this is an easy way to also focus on the consumer, designing an experience that caters to the type of audience your API is marketed towards.

In the REST ecosystem, the OpenAPI Specification (OAS) has emerged as the world’s standard for designing the interface. The OAS is a human and machine readable specification that’s language agnostic. It’s currently in its third version, with rich expressive capabilities for new security definitions, call backs, linking and more. The API’s definition in the OAS also opens up a world of possibilities in the form of mocking, generating server stubs, SDKs, test cases, and more.

For more visit our API Design Insights page

Virtualizing the API’s Dependencies

Your API is built for interoperability. As applications become increasingly complex with many dependencies and components, both internal and external, it becomes challenging to navigate all of these dependencies. This is where API virtualization comes into the picture. API virtualization is the process of creating a virtual called copy of your dependencies and mirrors specifications of your intended API. By creating a virtualized back-end off your API design, as well as mocking your dependencies, you can –

  • Allow your frontend and backend teams to work in parallel
  • Create a mock API with dummy data, and distribute that to a few stakeholders both internal and external and get that early feedback and deliver API greatness

API virtualization and mocking is is fast catching on due to its many advantages. This article can help you better understand the concept and benefits of API virtualization.

Building the API’s Business Logic

This is the phase where you take your machine and human-readable API design layer and convert that into actual code and business logic. Choosing the right technology framework is really important in this phase and luckily they open API design layer being language-agnostic can allow different developers in teams to do API business logic in different languages. Of course there are many different ways to choose the right programming languages, so here’s an article that can help. Tools like the Swagger Codegen project allow you to prototype APIs faster in the programming language of your choice by auto-generating boilerplate code from your API design. The code generator takes care of all the scaffolding in the API’s code, so your development seems to focus on what truly matters – the APIs business logic.

Testing the API

The testing phase is intended to reveal bugs, inconsistencies or any sort of deviation from what the expected behavior of the API was. depending on the mission criticality off your APIs you can perform different types of tests to ensure they function as intended. There are many different types of tests you can do like functional testing, reliability testing, load testing, and security testing, all of which can be prioritized based on your API’s objectives and target audience.

Creating API Documentation

Your API documentation is the face of your API. Think of it as a technical content deliverable that contains instructions about how to effectively use and integrate with your API. It’s a concise reference manual with all the information required to work with the API, supported by tutorials and examples.

Developers can auto-generate documentation from the OpenAPI definition layer through various API documentation tools. Documentation has a direct impact on adoption and growth of your APIs. The level of sophistication of your documentation can vary depending on the APIs use case. If it’s internal APIs, then maybe just reference documentation can suffice. External APIs tend to require higher levels of investment, with SDKs, tutorials, and a getting started guide.

Step 5: Define KPIs

A Key Performance Indicator (KPI) is a measurable value that demonstrates how effectively your API is achieving its business objectives. While your API is being developed, it’s valuable to understand exactly what are some quantifiable measures of success for your API program. It’s easy to get lost in a sea of potential KPIs you can measure yourself against, so tying your measurable outcomes back to your API’s purpose and audience, defined in steps 1 and 2, can help. There’s two types of metrics you should measure yourself against.

Audience Journey Metrics

This is characterized by measuring the various steps it takes for your end user to reach and consume your API. Here’s a classic example of KPIs for a traditional API model.

StageConsumer ActionKPI
Interest for using APIRegistering for API keyTime to register and obtain key
Desire for using APIUnderstanding how to use the APITime to first 200 response from API
Desire for using APIIntegrating with APINumber of API calls made over time
Advocating for the APISharing APIs among social and professional circlesNumber of shares made over time

The importance of measuring yourself against quantifiable metrics could decrease when building a private API, which may not necessarily require the same amount of rigor. That said, In case of private APIs, qualitative feedback and anecdotes can serve as good yardsticks to measure yours API against too.

Business Goal Metrics

These metrics are tied more closely to your API’s purpose. If it’s a public or partner based API model, then pricing and growth are good indicators of your API success. If your API is for private, internal use, then the number of applications and processes integrating with the API is a good measure of success. Here’s a few examples of business-centric KPIs.

Business Goal of APIKPIExample
Direct MonetizationIncrease in MRRTwilio
Indirect MonetizationNew customers referred through APIeBay
Package MonetizationCustomer lifetime value of customers using apps built through APISalesForce

Step 6: Collecting and Acting on Feedback

The metrics you define above can help you set benchmarks when collecting feedback on the quality and business value of your API. Once you’re done with the above phases, deliver the APIs on a basic portal to enable consumption by the right stakeholders, and get feedback. This step is all about getting some valuable feedback from an initial sample size of potential users. There are two parts to this step –

  1. Identifying early adopters who can provide you with feedback. You can leverage relationships with some of your existing customers, or scour for early adopters in channels where they usually hang out. This article from Lean Startup can be beneficial in understanding how to obtain early adopters
  2. Collecting and consolidating the feedback, and iterating on it.

This feedback needs to be processed and acted upon quickly, as part of the build-measure-learn philosophy. New feedback is again incorporated into the API design and development process, releasing new updates constantly.

Step 7: Marketing the API

Marketing your API is about educating your consumers on its benefits, and advocating for why it can be an integral part of the developer’s toolchain. At the end of the day, you want to make sure your APIs are being discovered and consumed, both internally and externally. In general, marketing is a combination of inbound content, including (includes inbound messaging and documentation) and outbound evangelism. This Nordic API ebook explains in detail the various stages to build a successful marketing program around your API, including various stages like establishing and maintaining developer relations, creating tutorials, and creating an advocacy program around your APIs.

Closing Notes

Building APIs with the end consumer in mind is the foundation of product thinking. Product based thinking tries to find a balance between the end consumers, business and the technology, while incrementally building a solution that provides real, sustainable value.

Keshav Vasudevan

About Keshav Vasudevan

Keshav is the Product Marketing Manager for Swagger and SwaggerHub at SmartBear Software, and helps communicate the value of definition driven API development to the software and developer community. He enjoys translating product value into actionable recommendations to help teams succeed in the API economy. He is also passionate about building products, and works on mobile and web applications on the side to keep himself busy. You can always reach him on Twitter: @keshinpoint