Mastering API product design and delivery

The way you design your API product can make the difference between a winning product that takes off rapidly and one that never really seems to get off the ground. If you want your API to be easily discoverable and adoptable, then follow our simple steps to API productisation below.

Great API product design starts with great API modelling

Making an API product that is consumable, performant and fulfils a need means starting with defining its goals and use cases. This API modelling process requires a clear understanding of your target audience, including their needs and pain points, so it’s time to do some research. Make sure to build a solid business case for your API product and obtain initial buy-in from your stakeholders.

From that perspective, remember that an API product is no different from any other product. Before starting the development phase, you’ll need to make sure that the product design meets a need, that you know who you are aiming it at and that the solution you are designing is both feasible and affordable.

API design fundamentals

Decisions you make at the API design stage can have a major impact on how well your API product ends up being received. If you design your API poorly, or your developer portal provides insufficient self-service tools to access APIs and debug integration flow, or your documentation is confusing, or your software development kit (SDK) inconvenient, developers will find it hard to adopt your product.

This will mean that integrations take longer and cost more, resulting in a low adoption rate or a high churn rate. Or possibly both. As such, it’s essential to prioritise matters such as your access flow and analytics right from the outset.

Understanding the nature of the business process with which your API will interact is crucial here. This will dictate how you implement your API product, enabling you to factor this into the design. For instance, if the integration process will be asynchronous by nature, as is the case with delivery services or HR software, then you need to consider implementing webhooks for the asynchronous parts of it.

Design decisions will vary depending on the needs of your customers, which is why understanding customer pain points and goals is so fundamental to the API modelling process that precedes the design phase. Do your customers, for example, want to integrate your service into their Salesforce instance to automate error-prone manual tasks and save time for their employees? Or are they introducing a new feature to their mobile app to increase customer engagement?

All of this contributes to your design decisions: all aspects of your API product should factor it in, from authentication to SDKs and self-service facilities. Whatever your customers’ priorities are, designing well with these in mind will bode well for your eventual adoption rate.

Designing for your business

Right from the outset, you need to design a product that is beneficial to your business. That means thinking about how your API product is going to make money and how you are going to monitor its value to your business. 

There are various monetisation strategies you could use, including direct and indirect monetisation or revenue share schemes with your consumers. However, when you’re designing your API, no matter which monetisation model you have in mind, you’ll need to ensure you deliver high value to your customers, while also ensuring that the profit you make covers the cost of maintaining and evolving your API and providing support to your consumers.

You’ll need to ensure that the value your customers receive from using your APIs is expressed in their cost savings, increased profits, lower security risks or other tangible metrics. Doing so needs to justify the price of your APIs and what it costs in time and effort for customers to integrate with them. Otherwise, it won’t make sense for consumers to get started with your APIs.

Designing for your users

During the discovery process, you may realise that there are multiple segments of customers who differ in their jobs to be done, organisation size, industry and so on. You will need to define these features precisely, as they are key to understanding the market size and quantifying the business opportunity that your API product presents.

You also need to understand what success looks like for these customers, as well as how they plan to measure it. These insights are crucial for successful product design. Understanding them will also help your marketing team to define your unique selling point (USP) in a way that aligns with your customers’ aims.

Unlike web products, where you can tailor the user interface for a specific audience dynamically, such an option is not available for REST APIs – although you can leverage GraphQL APIs and let your customers define which fields in your APIs they would like to use!

You need to consider the requirements of all segments and find a common ground for them. At the same time, there are no limits on how you can position and market your API product. For instance, you can create call to action (CTA) messages specifically designed for each of your audience’s segments, such as different statements explaining the benefits for large enterprise customers or small and medium enterprises (SMEs).

Designing for developers

As well as designing your product with your target customers’ pain points and goals in mind, you need to think about those who will be using your API – developers. Researching their maturity, authorisation requirements and any preferred languages in their industry means your API product can be designed to dovetail beautifully with the requirements of those who will be using it.

One very important aspect of this is self-service access and debug tools. Your developers cannot adopt your APIs if they cannot access and integrate with them. Instead, they will flood your customer support with requests for access, rotating credentials and debug-related questions, resulting in both high operational expenses and low adoption. Definitely not ideal. 

Understanding these requirements can also save you time and effort. Knowing which languages your intended users prefer, for example, means you won’t waste time building SDKs for languages that aren’t suited to your API’s specific use-case.

Fitting your API product to your market

First of all, you need to design your product at a higher level: define its user flow, USP and pricing model. Then, validate your value proposition with a series of interviews with decision-makers. Most likely they won’t be interested in technical design of your product so before you proceed with that, you must be sure that the product actually solves your customers’ problems. If it doesn’t, they won’t use your product, no matter how beautifully it’s designed from a technical standpoint. 

Your interviews with decision-makers should focus on validating your vision of the solution and the business model. First, create a sales pitch to outline your vision of what you think might solve your customers’ problems. 

Next, check if your customers are willing to buy a solution from you based on your pitch. If so, what price range are they willing to pay? This can be tough, so it’s good to come up with a set of predefined ranges to test.

It may require iterating multiple times over your solution before you find a good problem-solution fit, but this will pay off when you crush the market.

The technical part

From a technical perspective, you need to design the API, including endpoints, authorisation and authentication mechanisms, data structures, security and so on. Standardisation is certainly your friend here, as it will help you to design an API that feels intuitive for developers to work with. 

You don’t need to reinvent the wheel when it comes to API design. There are plenty of solutions that can help you speed up the process. Tyk Designer, for example, enables you to design your API from scratch or import your API via OpenAPI Specification (Swagger) to enable CI/CD, with the added bonus of easy documentation of your API design.

Once you have the specification and the user flow for accessing your API product in place, you need to test the spec feasibility. This means booking a series of interviews with your developers audience and undertaking user experience (UX) and developer experience (DX) tests: present developers with the spec and ask them how they would build the integration flow with it. Are the provided endpoints enough for integration? Do they need to transform the data before using it? You need to consider all of this to secure flawless adoption.

If you tick all the right boxes at this stage, it’s time to move on to delivering your API.

API product delivery 

When it comes to the delivery of your API product, success means the API does what it should, has clear, concise documentation and comes packaged with a customer-centric support service. Writing clear documentation is not enough. You documentation should speak the same language with both developers and decision makers. Having business documentation separated from general marketing content is key to this.

When implementing the API, the first step to this is to write the code and test it thoroughly to ensure your API is efficient, performant, secure and scalable. Test, test and test again to ensure that you are confident your product will perform as expected once published. 

Your documentation, meanwhile, needs to be both comprehensive and concise. It should cover everything developers will need to adopt and use your API, including troubleshooting, in an easy-to-follow format. 

Not to wave the Tyk flag too overtly, but a powerful, intuitive API management solution can certainly help with all of this.

Developer onboarding

Once you’ve tailored your packages and published your API, you need to ensure that developers can discover and access it. This is where a developer portal comes in. A developer portal can showcase your API products, packaged together with documentation targeted at your intended personas and/or market segments. You also need to ensure your developers can onboard your API products. As a wise man once said, API catalogues organise, while developer portals productise.

Developers need to be able to find your API and understand its purpose and function. This is key to enabling self-service discovery and consumption of your API product – and doing so is essential if you want to scale as rapidly and widely as possible. 

You will likely want to launch your API product with some fanfare too and market it to your target audience. Ensure that you do so in a way that’s aligned with your wider business strategy and objectives to keep all messaging on brand.

The developer portal is an integral part of your API offering: poorly designed access-flow or lack of self-service debug tools will result in painful adoption, an increasing number of support tickets, or both. This means you also need to test it before bringing it to market.

Book a series of interviews with your developers and ask them to go over the interface of your developer portal to make sure that the interface is well understood, the access flow doesn’t have any friction and the self-service debug tools are sufficient.

Ready, set, go!

That’s it – you’ve mastered the basics of API product design and delivery. Then all you need to do is put processes in place for maintenance, improvement, versioning, customer support and all the other things you need to keep your product relevant and your customers happy. 

It’s worth noting as well that many of the above points also apply to internal API development. You still need to design your API with consumers in mind, produce helpful documentation, design securely, deliver in terms of performance and so on. 

Got questions? The Tyk team is happy to talk about how our API management solution can help you design and deliver your API products. You can also dive straight in and try Tyk for yourself with no commitment. Why not get started on your API productisation journey right now?