Why do Start with API Design?
APIs that are easy to consume are APIs that get used. Conversely, poorly designed APIs that don’t get consumed lock away value that can’t be realized. Creating well designed APIs increases your ability to leverage the potential value of that API and turn it into realized value. APIs that are easy to use are adopted quickly and reduce the burden of integration cost, in real time and materials, for all those involved.
So what is a well designed API?
- It should embody consumer centric positioning. We should use language that is natural to our API consumers.
- It should be self-evident and intuitively designed
- It should be of real utility, solving an identified need for your API consumer.
Are you considering:
- How will you standardize API contracts and behaviors across teams?
- How will you enforce these standards across teams in a way that doesn’t sacrifice speed?
- How much technical debt are you accruing with your current practices?
- How you will federate security patterns and practices?
- How do you know if the designs you are producing are natural for your API consumers?
Productization is 80% packaging/20% design
Productization is all about packaging APIs to simplify otherwise complex consumption. You should package in a way that is relevant to solving your consumers’ use cases. And your consumers should be able to easily understand that it solves their needs. This is what productization is really about.
Because packaging is about clarifying common consumer use cases, it will need to include specific use case guidance. Customer use cases almost always span multiple APIs, so your package will often include cross API documentation. Packages should also support familiar brand and product messaging. This all creates a more familiar experience for your API consumer and helps enable their independent consumption of your APIs. Consumer independence is a core principal required for any level of scale.
Are you considering:
- How to systemize outside-in design practices?
- How to bridge the business and IT with new practices and roles like API Product Owners?
- How to Measure the value your API provides to your customers and to the business with identified objectives and key results (OKRs)?
- Who is responsible for packaging vs. documentation vs. specifications?
- How to know if your packaging is simplifying the experience, or in fact making it more complex for your consumer?
Establishing an API Marketplace
Your developer portal is a marketplace for your API consumer to discover available digital products, to self-educate, requisition access, test and consume, etc. It’s also the first place your consumer will go when something is broken or they need something new. Your API Marketplace should facilitate your consumer’s API experience from end to end.
Let’s look at a complimentary pattern. Websites have come a long way over the last 20 years, maturing from online brochure-ware to rich engagement platforms that create competitive difference and cultivate customer loyalty. At the heart of this progression, there is an obsessive focus on the customer experience and quality of digital interactions.
Your API Marketplace is also a digital engagement channel, focused on your API consumer. Whether your API customers are internal or external, don’t make the mistake of thinking your Developer Portal is simply a more convenient place to house your API documentation. We’d be throwing away 20 years of learning and promoting this generation’s equivalent of web 1.0 brochure-ware as the next best thing.
Are you considering:
- How you will attract your community?
- How you will create intentional journeys for each of your consumer segments?
- How will you know what is effective in your marketplace experience and what is not?
- How you will engage your community for feedback?