11 Lessons Learned as an API-first Product Manager

1) Segment every conversation

Compared to traditional user interfaces that are consumed by many different personas (marketing teams, administrators, developers); APIs are typically developed for consumption just by developers. This makes building an API a more technical journey compared to UIs. However all the components that are applicable to traditional product building apply equally here – justifying a business case, feature prioritization, user validation, user stories, internal and external thought leadership & education, positioning and value communication, etc. The audience for these exercises may or may not be your core users, or even technical in nature.

This is where the need arises to consciously segment every conversation. Anticipate whether your audience cares about the ‘why’ behind your product or the ‘what’. Typically buyers (CTOs, CIOs), internal executive teams & architects care about the ‘why’ while developers, technical sales & evangelism teams care about the ‘what’ – but these boundaries are more and more blurred as organizations get more technical.

Building on the above, both technical and non-technical decision makers will be critical to the success of your product. A single API endpoint is likely 10x more powerful than its equivalent UI button – but is likely 10x more difficult to see that value as well. As the product visionary, the onus is on you to empower others to see that value. You need to be judicious on when you choose to go deep into the product and when you choose to go wide in conversations. Some API consumers might prefer to understand the bells and whistles of a particular endpoint so they can fulfill a task they have in mind. Others might want to understand your vision for where the API plays in a high level ecosystem, to help them derive value. As a thumb rule, when talking to non technical decision makers, leverage reference architectures and business objectives to drive your message. When talking to technical decision makers, use API docs or even better – a demo!

3. Start with the right global and local success metrics

Building APIs need attention to a high level of detail. It can however be easy to get lost in this. As you go through the API building journey, there are many metrics you will need to track – uptime, error rates, latency, requests over a period of time, average and max request rates, # of client tokens per endpoint, # of active users, retention, etc all will play critical parts. To avoid getting lost, a good tactic is to use Google’s philosophy of ‘Global’ and ‘Local’ metrics. Global metrics are ones that define success and are shared more broadly. Local metrics are the ones that enable success and are tracked within your core team. Fox example, consider my biggest goal for a new API is to drive new users to my platform & make them sticky. I will have the following:
Global Metrics: # of new users per month, # of active client tokens per week
Local Metrics: Uptime, Time to First Hello World, 95th percentile Response Time, # of Requests per month, Average System Compute Time per call, Average 4xx & 5xx errors per month, % of users without any 5xx errors per month, API calls per Business Transaction

APIs are misleading. The most effective APIs are often the ones that look like innocuous endpoints but pack a ton of underlying value driving end user stickiness and functionality. This ability to simplify the end user endpoint interface is key to empowering targets users get up and running with your API. This often includes two key components:
i) Hands free onboarding: leverage popular API authentication methods such as API keys, JWT tokens, and OAuth to provide a simple setup experience. Each of these comes with its own cost benefit trade-off – for example, today OAuth2.0 is known to provide the simplest user experience but can be the trickiest for your developers to implement.
ii) Use Case mapped endpoints: As a thumb rule, come up with a list of use cases you want to unlock, and target one API endpoint per use case. Typically use cases are structured around exposing CRUD (Create, Read, Update, Delete) operations for every task performed.

5. API Documentation is your new user interface. It can make or break adoption

Unlike a Graphical User Interface (GUI), APIs don’t provide the real estate for users to figure things out intuitively. API documentation is the only self-serviceable way for consumers to understand the full potential of your API. Prioritize documentation in your backlog of setting certain internal guidelines:
– Any changes or updates cannot be released without the appropriate documentation being updated and release notes (change logs) going out
– Ensure API documentation is use case or workflow based, and includes examples
– Define test cases that ensure your engineering teams test against what is documented externally vs relying on internal domain knowledge. Include the entire API lifecycle from authentication to deployment in your test cases
– Ensure any debugging guidelines and system limits are documented clearly
– Avoid overly technical, verbose, or internal jargon in your API documentation

Generating a clear, concise API document and keeping it updated is hard. It is likely your organization already leverages API description formats such as SWAGGER/OPEN API to automate and standardize the process across teams. Prioritize integration into this. Remember, you can build the most powerful API that solves all your problems. But if nobody knows about it through your documentation, you might as well have not built it.

APIs are often defined as the connective tissue between microservices, applications, and systems. Translated naively, that means APIs typically serve a higher purpose than their core function. Ensure that this bigger picture is captured in your product backlog by focusing on tools, libraries, partner documentation, and partnerships that drive your API consumption. API integrations fall into two categories:
(i) Integrations focused on standardization: Orchestration tools such as Terraform and Ansible built on top of APIs significantly simplify and standardize consumption of APIs in a multi-cloud native world. They ensure developers do not need to learn the bells and whistles of constructing APIs for every vendor – leverage these tools to empower users to envision your APIs in their modern software stack. 
(ii) Integrations focused on unlocking value: 1+1=3. ‘Pluggability’ is especially important in today’s Kubernetes driven world where the unit of deployment is a container – users will look to build applications that reuse components from different vendors vs building everything themselves. Focusing on the right set of integrations here can unlock passive, hidden revenue streams and additional value

7) Your biggest wins might come from strangers. Go find them

APIs are lego blocks. If you ever played with lego blocks as a kid, think of friends coming over and creating shapes you never imagined. The same concept applies to APIs – you are lucky that your core user base tends to be technically gifted problem solvers (developers). As mentioned above, the pluggability enabled by APIs might unlock use cases, efficiency, and solutions you might have never envisioned. Ensure you facilitate collaborative developer ecosystems around your API that helps facilitate this innovation. Github and other community channels, hackathons, technology partnerships, etc are some good ways to foster this.

8) API versioning is your biggest enemy – but it doesn’t have to be

Anyone who’s remotely been involved in building an API probably has nightmares about this one. Compared to traditional user interfaces, APIs can almost be invisible. They might be integrated into automated workflows, forgotten test environments, ecosystem partner systems, etc. Updating a traditional UI requires a static update in one place you bring all your users into. Rolling out a new API version requires going into the millions of places your users live in. That leads to communication, backward compatibility issues, the risk of expensive corrections, etc. If you are to introduce API changes, I’d recommend two guidelines:
– Whenever possible, avoid breaking changes. That new field you are looking to introduce – does it really need to replace an existing field or can you get by with an additive approach where you continue to keep the old one?
– Use SemVer to communicate both breaking and non-breaking changes to your users. As a Product Manager you should be aware of at least the high level version semantics to ensure the right external communication. Trust me, it can be the difference between a fulfilling year filled with new ideas and innovation or a year immersed in user migration hell. 

Providing the right amount observability is going to be a fundamental element of any API building process. However that one requirement has the potential to quickly expand into many streams, variants, and an entire overwhelming backlog in itself. A good way to segment and translate customer conversations is to think of the following 4 high level requirements applicable to any good self-serviceable API:
(i) Error Logging: Ensure your APIs provide concise, actionable user errors with the right error response codes 
(ii) Tracing: Ensure both internal and external users can generate traces that identify root causes for any abnormal API behavior
(iii) Event logging: Ensure critical API calls (especially POST and PUT) can be audited at a later time. At a minimum this should include a who (user or client token) called what (endpoint name)  when (timestamp)
(iv) Internal availability and latency monitoring: Finally, verify that your engineering team has prioritized internal log alerts for availability, latency, and error rate thresholds; automated notifications; and remediation hooks for any SLO (Service Level Objective) violations.

10) Scale, scale, scale

Good API focused Product Managers are extremely hands-on in the API building process. The best API focused Product Managers know how to flip the switch when it is time to launch and refocus on higher value. Get marketing and sales teams excited about the value your API is driving. Get technical marketing and sales teams to focus on the higher value proposition when demo-ing your API – train your trainers to focus on parts that drive the most customer value and segment customers similar to you. The ability to scale your excitement is critical to any product launch. That ability is 10x more critical for APIs since that value communication is more likely to be lost downstream.

Finally, don’t be shy to build a more visual interface in case you have exhausted or are looking to go beyond all existing adoption avenues. Even if your initial target persona were technically savvy developers, GUIs can open up your products to non technical personas in the same organization. Marketing teams, buyers, business KPI owners, website administrators, non-technical sales teams, etc might potentially benefit from the value your API drives, but aren’t comfortable making API calls. Often even developers might find these more intuitive. While designing an API first experience is critical to modern application development, do not stop there – leverage these users to drive your next set of product value!