My previous posts have focused on developer experiences and APIs. A big theme in companies positioning themselves as “platforms as a service” i.e. be a pluggable value generating component within a more broader solution. This post focuses on building APIs and calls out 11 useful tips for building API centric platform products.
Platform driven products thrive by exposing APIs that integrate into broader technical stacks. Compared to tradition UI focused products that are consumed by various personas (marketing, sales, finOps, developers), these are solely consumed by developers. However all the rules of a traditional product lifecycle apply – justifying business cases, trade-offs & prioritization, user flows, customer validation, messaging 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 you need to segment every conversation as it takes place. 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’ – consciously communicate appropriately.
2. Words travel worlds. Translators do the driving. Be your organizational translator on value
Both technical and non-technical decision makers are critical to the success of your product. A single API endpoint can drive 10x more user value than an equivalent UI click – but it is 10x more difficult to intuitively see that value. The onus is on you to help others to see that value. Be judicious on when to go deep into the product and when to go wide in conversations. Some API consumers want to understand the bells and whistles of a particular endpoint since they have a specific task in mind. Others might want to understand the broader platform focused outcome for that API 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. Define the right global and local success metrics
Building APIs requires high attention to detail. It is however easy to get lost in this. You will want to track many metrics – uptime, error rates, latency, requests over a period of time, average and max request rates, # of client tokens per endpoint, # of active users, retention – all of which play critical roles. To avoid getting lost and keep stock of the bigger picture, use Google’s concept of ‘Global’ and ‘Local’ metrics. Global metrics track outcomes and are shared more broadly. Local metrics track indicators that enable these outcomes and are tracked within your core team.For example, if a new API’s aims to drive users to your platform & make them sticky, sample metrics are:
Global Metrics: # of new API keys per month, # of active API tokens per week
Local Metrics: % Availability, 95th percentile Response Time, # of Requests per month, Average System Compute Time per call, Average 4xx & 5xx errors per month
4. A zero-effort API call is the North Star
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:
– No changes released without corresponding documentation and release notes (change logs)
– Include scenario based recipes when multiple API calls are needed to achieve an outcome
– Define test cases to stress test published documentation vs relying on internal domain knowledge. Include the entire API lifecycle from authentication to deployment in these
– Any debugging guidelines and system limits are documented clearly
– Avoid overly technical, verbose, or internal jargon
Pro Tip: Leverage your community for documentation updates. Building your general doc platform on an interactive Github based CMS can drastically speed up internal and external contributions.
6) It’s not all about you (or your API). Integrations & SDKS are your best friend
APIs are described 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 infrastructure as code tools, libraries, partner documentation, and partnerships that drive your API consumption.
API integrations fall into two categories:
(i) Standardization focused Integrations: Orchestration tools such as Terraform & 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 & provide more auditability around changes – leverage these tools to empower users to envision your APIs in their software stacks.
(ii) Incremental value driven Integrations: 1+1=3. ‘Pluggability’ is especially important in today’s Kubernetes driven world where the unit of deployment is a container – users want to build applications that reuse components from different vendors. 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). The plug and play nature of APIs might unlock use cases and solutions you might have never envisioned. Enable collaborative developer communities around your API to facilitate this innovation. Github, community channels such as Stack overflow, hackathons, technology partnerships, etc are good ways to foster this.
8) API versioning is your biggest enemy – but it doesn’t have to be
Anyone involved in building APIs likely has nightmares about versioning. Compared to traditional UIs, APIs flows are often 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 millions of places your users live in. This leads to communication challenges, backward compatibility issues, lots of unpredictability, and ultimately angry customers. Here are two critical guidelines for any versioning rollouts:
– Avoid breaking changes whenever possible: 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.
9) Don’t be a black box
Providing end to end observability is a fundamental to of any API building process. Leverage the holy trinity of observability – metrics, logs, and traces to achieve this end to end visibility:
(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 events (especially POST and PUT) can be captured and are auditable. At a minimum these event logs should mention who (user or client token) called what (endpoint name) when (timestamp)
(iv) Availability and performance metrics: Finally, verify that your engineering team is using automated alerts around availability, latency, and error rate thresholds; and has the necessary remediation flows for any SLO (Service Level Objective) violations.
10) Scale your organization when it is launch time
Good APIs often require extremely involved product management. However 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.
11) Sometimes, it might just be time to put a more intuitive user interface on your roadmap
Finally, don’t be shy to build a more visual interface to compliment your . 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 ramp up your product adoption!
