api & developer experience pm
When your user is a developer, your UI is your documentation and your onboarding metric is time-to-first-API-call. If it takes more than fifteen minutes to get a 200 OK, you have already lost them to the competitor whose docs got them there in five.
Most PM roles let you build interfaces that humans interact with. Buttons, forms, dashboards, flows. You can watch a user struggle. You can run a usability test. You can see where they tap and where they drop off.
API and developer experience PM is different. Your user is an engineer. They will never open your marketing site unless they are desperate. They will never watch your product tour video. They will read your API reference at 2am while debugging a production integration, and they will form their opinion of your entire company based on whether your error messages tell them what went wrong or return {"error": "something went wrong"}.
After training thousands of PMs, I have seen maybe a dozen who truly understood developer products. The rest applied consumer product instincts — beautiful onboarding flows, guided wizards, tooltips — to an audience that actively rejects those things. Developers do not want to be guided. They want to be unblocked.
Your user does not want your UI
The single hardest mental shift for a PM moving into developer products: the interface is not the product. The API is the product. The documentation is the product. The error messages are the product. The SDKs are the product.
A developer evaluating your payments API does not care about your admin dashboard. They care about three things, in this order:
- Can I understand what this API does in under two minutes? Clear naming, logical resource structure, a one-paragraph overview that tells them what the API covers and what it does not.
- Can I make my first successful API call in under fifteen minutes? A quickstart guide with a working curl command, a real API key (not a placeholder that requires three email verifications), and a sandbox that actually works.
- When something breaks, will the error message tell me what I did wrong? Not
400 Bad Request. NotInternal Server Error. A message that says: “Theamountfield must be in paise, not rupees. You sent 500, which would charge ₹5.00. Did you mean 50000?”
If your product nails all three, developers will forgive almost everything else. If it fails on any one of them, no amount of marketing spend will save you.
This is why Stripe won. Not because they had better payment processing — dozens of companies process payments. They won because a developer could go from zero to a working payment integration in an afternoon. The API made sense. The docs were honest. The error messages were helpful. Every other payments company at the time treated documentation as an afterthought. Stripe treated it as the product.
API design is a product decision, not an engineering decision
Here is where most companies get it wrong: they let engineering design the API and then ask the PM to “write the docs.” This is like letting the factory design the car and then asking marketing to write the owner’s manual. The API is the user interface. It should be designed with the same rigour you apply to any user-facing product.
Naming is UX. An endpoint called /api/v2/txn/init tells the developer nothing. An endpoint called /payments/create tells them everything. Resource names, field names, parameter names — these are the nouns and verbs of your product’s language. Developers will type them hundreds of times. They will appear in codebases for years. Get them wrong and you are stuck with a bad name forever, because renaming is a breaking change.
Versioning is product strategy. How you version your API determines how painful it is for customers to upgrade, how long you support old versions, and how much technical debt your engineering team carries. URL versioning (/v1/, /v2/) is explicit and easy to understand. Header versioning is more elegant but harder to debug. Date-based versioning (Stripe uses this — 2024-06-01) lets you introduce changes granularly without forcing a full version migration. The choice is not technical — it is a product trade-off between developer experience and maintenance cost.
Error messages are support tickets you prevent. Every vague error message generates a support ticket. Every clear error message prevents one. At scale, this is not a nice-to-have — it is a cost structure decision. If you have 10,000 developers integrating your API and each vague error generates 0.1 support tickets, that is 1,000 tickets you created by being lazy with error messages. A PM who treats error message design as beneath them does not understand developer products.
Rate limits are a product feature. How many requests per second? Per minute? Per API key? Per endpoint? What happens when a developer hits the limit — do they get a clear 429 with a Retry-After header, or do they get a mysterious timeout? Rate limits communicate your product’s capacity and constraints. They should be documented, predictable, and generous enough that developers can build real applications without constantly hitting walls.
Consistency is more important than perfection. If your /payments endpoint uses created_at for timestamps and your /refunds endpoint uses createdAt, developers will hate you. Not because either format is wrong — because inconsistency means they cannot predict your API’s behaviour. They have to check the docs for every single field on every single endpoint. A consistently designed API lets developers guess correctly. An inconsistent API forces them to look everything up.
Documentation IS the product
I am going to say something that will sound extreme: for an API product, if your documentation is bad, your product is bad. Full stop. No qualification.
A developer cannot see your clean architecture. They cannot appreciate your elegant microservices. They cannot feel your 99.99% uptime. All they can see is the documentation. If it is incomplete, outdated, or wrong, that is their experience of your product.
What good API documentation contains:
A quickstart that actually works. Copy-paste the curl command. It should return a real response. Not a “follow these 12 steps to create an account, verify your email, generate a key, configure your environment…” Just a command that works. Razorpay’s API docs do this well — you can make a test payment in minutes, not hours.
Complete API reference with every field documented. Every endpoint, every parameter, every possible value, every error code. If a field can be null, say so. If a field is deprecated, say so. If a field behaves differently in test mode versus live mode, say so. Developers should never have to discover behaviour by trial and error.
Guides for common use cases. The reference tells you what each endpoint does. Guides tell you how to combine endpoints to accomplish a task. “How to implement subscription billing,” “How to handle webhooks for payment status updates,” “How to migrate from API v1 to v2.” These are the documents developers actually read, because they map to the problems developers actually have.
Changelog that tells developers what broke. Not “various improvements and bug fixes.” Every API change that could affect an integration, documented with the date it takes effect and what developers need to do. Breaking changes need migration guides, not just release notes.
Postman built a $5 billion company essentially on the insight that API documentation and testing were so painful that developers would pay for a tool to make them less painful. If your product’s documentation is so bad that developers need a third-party tool to understand it, you have handed revenue to Postman that should have been yours.
The pit of success
There is a design principle in developer experience called the “pit of success” — coined by Rico Mariani at Microsoft. The idea: make the correct usage of your product the easiest usage. Make developers fall into doing the right thing.
The opposite — the pit of despair — is what most APIs create. The default behaviour is wrong. The obvious approach is the insecure one. The simple path leads to a production outage.
Examples of pit-of-success design:
- Default to secure. If your API key can be used from both frontend and backend, the default should be backend-only. A developer who accidentally exposes a frontend-capable key in a public GitHub repo should get a restricted key, not a full-access one.
- Pagination should be mandatory, not optional. If a developer can call
GET /transactionswithout pagination and get back 50,000 records, you have designed a pit of despair. Default to paginated responses. Make the developer explicitly opt into larger page sizes. - Idempotency by default. If a developer’s network times out during a payment creation and they retry, the default should be “detect the duplicate and return the original result,” not “create a second payment.” Stripe’s idempotency keys are a pit-of-success design — one header prevents an entire category of bugs.
- Sandbox environments that behave like production. If your test environment silently accepts invalid data that production rejects, developers will discover their integration is broken only when they go live. The sandbox should reject the same things production rejects.
As a PM, your job is to audit every developer interaction with your product and ask: “What is the easiest thing a developer can do here? Is it the right thing?”
Developer experience metrics
You cannot manage developer products with consumer product metrics. DAU, session duration, NPS — these tell you almost nothing useful about an API product. Here is what matters:
Time to first API call (TTFAC). From the moment a developer signs up to the moment they receive their first successful API response. This is your onboarding metric. Measure it in minutes. If it is above thirty minutes, your onboarding is broken. If it is above sixty minutes, you are actively losing customers to competitors.
Integration success rate. What percentage of developers who start an integration complete it? If 1,000 developers sign up and 200 successfully make their first API call, your integration success rate is 20%. That means 800 developers tried your product and gave up. Each one of them had a specific reason. Find it.
SDK adoption rate. You offer SDKs in Python, JavaScript, Java, Go, Ruby. What percentage of API calls come through each SDK versus raw HTTP? High SDK adoption means your SDKs are good and your documentation steers developers toward them. Low SDK adoption means developers either do not trust your SDKs or do not know they exist.
Support ticket volume by category. Not just total tickets — tickets categorised by root cause. If 40% of your support tickets are “how do I authenticate?” your authentication docs are bad. If 30% are “webhook delivery failed,” your webhook infrastructure is unreliable. Support tickets are a direct signal of product failure in developer products.
API error rate by endpoint. Which endpoints generate the most 4xx errors? High client error rates on a specific endpoint mean developers are misusing it — which means the API design or documentation for that endpoint is unclear. This is not a developer problem. It is your problem.
Time to resolution for integration issues. When a developer files a support ticket, how long until their integration works? In consumer products, a slow support response means an annoyed user. In developer products, a slow support response means a company’s launch is delayed. Their CTO is asking why the integration is not done. Your response time directly affects your customer’s business outcomes.
SDKs and client libraries: building for five languages matters
Your API is language-agnostic. Your developers are not. A Python developer and a Java developer think differently, structure code differently, and have different expectations for how a library should behave.
If you only offer a REST API with no SDKs, you are asking every developer to write their own HTTP client, handle authentication, parse responses, manage retries, and implement error handling from scratch. Some will. Most will resent it. And each of them will implement it slightly differently, which means each of them will encounter different bugs.
The SDK question for a PM is not “should we build SDKs?” — it is “which languages, in what order, and to what quality bar?”
Prioritise by your developer population. Look at your API access logs. What languages are developers using? If 40% of your traffic comes from Node.js applications, your JavaScript SDK is your most important SDK. If you are selling to Indian enterprise companies, Java and Python will dominate. If you are selling to startups, JavaScript and Python.
Official SDKs must be better than community SDKs. If a developer finds a community-maintained Python library that is better than your official one, your official SDK is hurting your brand. It signals that you do not care about that language’s developer community. Either invest in making your official SDK excellent or endorse and support the community SDK.
SDK design is product design. A good SDK does not just wrap HTTP calls. It provides type safety, sensible defaults, automatic retries with exponential backoff, and idiomatic patterns for the language. A Python SDK should feel like Python. A Go SDK should feel like Go. If your SDKs all look like thin wrappers around the same HTTP client, they are not SDKs — they are code-generated boilerplate.
India is producing more developers than any country except the US. Razorpay, Postman, Chargebee, Freshworks Platform, Hasura, Appsmith — Indian companies are building some of the most developer-facing products in the world. The developer population here skews heavily toward JavaScript and Python. If you are building a developer product in India, those two SDKs are non-negotiable on day one.
India is becoming an API-product hub
This is not an aside — it is a career observation. India’s developer population is the second largest in the world and growing faster than any other country’s. That raw number creates demand for developer tools and API products that simply does not exist at the same scale anywhere else.
Postman was founded in Bangalore. It is now used by 30 million developers globally. Razorpay built India’s most developer-friendly payments API and became a decacorn. Chargebee built subscription billing APIs from Chennai and went public on NYSE. Freshworks built an entire developer platform on top of its CRM products. Hasura built a GraphQL API layer that is used by companies worldwide. Appsmith built an open-source internal tools platform that developers adopt because it respects their workflows.
These are not coincidences. India has the developers, the engineering talent, and increasingly the product talent to build world-class API products. The PM role in these companies is fundamentally a developer experience role. If you are a PM in India looking at the next decade, understanding API design and developer experience is not a niche specialisation — it is increasingly where the most interesting PM roles are.
The companies that are hiring developer experience PMs in India right now — Razorpay, Postman, Freshworks, Hasura, Chargebee, Zoho (for their developer platform), and a growing list of startups — are paying at the top of the market because the supply of PMs who understand both product management and developer workflows is tiny.
Thursday afternoon. An API-first fintech company in Bangalore. The team is debating whether to release API v3, which redesigns the transaction endpoint but breaks backward compatibility.
PM: “The current transaction endpoint has three known design flaws — inconsistent field naming, no support for idempotency, and the error responses are generic. We have 200 support tickets a month because of these issues. V3 fixes all of them.”
Engineering Lead: “V3 is ready. It is a clean redesign. But 200 active customers are integrated on v2. Every one of them has to update their code.”
PM: “I want to ship v3 as the default for new integrations and give existing customers twelve months to migrate. We keep v2 running with no new features.”
Engineering Lead: “Twelve months of maintaining two versions? That is a significant engineering cost. Every bug fix has to be applied to both.”
PM: “What is the alternative? Force-migrate 200 customers in sixty days? We tried that at my last company. We lost 15% of them.”
Head of Developer Relations: “Can we do a compatibility layer? A shim that translates v2 requests to v3 internally? Customers do not have to change their code, but we only maintain one codebase.”
PM: “That works if the request and response shapes are similar enough. Engineering — is the v3 schema close enough to v2 that a shim is feasible?”
Engineering Lead: “For 80% of the fields, yes. The remaining 20% are the breaking changes — the ones that fix the actual design flaws.”
PM: “Then here is the proposal: compatibility shim for the 80%. For the 20%, we add the new fields alongside the old ones in v2 responses — both present for six months. Developers can migrate field by field instead of all at once. We deprecate the old fields after six months with clear warnings in the response headers.”
The PM chose a path that respects existing integrations while still fixing the design problems. The hardest part of API PM is not designing the right API — it is migrating the world from the wrong one.
Breaking backward compatibility fixes your design debt. It also breaks your customers' production systems. The PM has to find the path that does both.
The documentation-as-product mindset
If you take away one thing from this page, make it this: in developer products, documentation is not a deliverable you write after the product ships. It is the product surface that developers interact with. Every bad doc is a lost customer. Every outdated example is a support ticket. Every missing guide is a competitor’s opportunity.
This means documentation gets the same product management treatment as any feature:
- Documentation has a roadmap. Not just “update the docs when we ship.” A plan for which guides to write, which examples to add, which tutorials to create. Prioritised by developer pain — the topics that generate the most support tickets get documented first.
- Documentation has metrics. Page views, time on page, search queries that return no results, bounce rates on quickstart pages. If 60% of developers leave your quickstart page without completing the tutorial, your quickstart is broken.
- Documentation has user research. Watch a developer try to integrate your product using only your docs. Do not help them. Do not explain things. Just watch. Every question they ask out loud is a gap in your documentation. This is the most valuable research a developer experience PM can do.
- Documentation has quality gates. Every code example must be tested. Every API call in the docs must be run against the current version. If an example in your docs returns an error, your documentation is lying to developers. Stale examples are worse than no examples — they waste time and erode trust.
Test yourself
You are the PM for a developer platform at a fast-growing Indian SaaS company. Your API has a payments endpoint — /transactions/initiate — that was designed two years ago. It has three known problems: the field naming is inconsistent (mix of camelCase and snake_case), error messages are generic ('Bad Request'), and there is no idempotency support. 200 active customers depend on this endpoint in production. Your engineering team has built a clean v2 of the endpoint that fixes all three problems. Shipping v2 would break every existing integration.
Your engineering lead wants to ship v2 next sprint and deprecate v1 immediately. Your head of customer success is panicking about customer churn. Your CEO wants to 'just fix it.' You need to decide the migration strategy.
your path
Pick any API product you do not currently use — Razorpay, Stripe, Twilio, Postman API, Freshworks API, or any product with a public API. Set a timer for 45 minutes and try to:
- Sign up for a developer account
- Get an API key
- Make your first successful API call
- Handle an error case (send a deliberately malformed request)
Document every friction point:
- How long did it take to find the quickstart guide?
- Was there a working curl command you could copy-paste?
- Did the API key work immediately, or did you need email verification first?
- What did the error message say when you sent a bad request? Was it helpful?
- Did you need to read more than one page of docs to make your first call?
Now compare your experience against the metrics: was your time-to-first-API-call under fifteen minutes? If not, identify the specific step that took the longest. That step is the product’s biggest onboarding problem.
If you want to go further, try the same exercise with a competing product and compare the two experiences side by side. The difference in TTFAC between two competing APIs is often the difference in their market share among developers.
You are PM for Razorpay's payment APIs. A major enterprise customer (Zomato) reports that the API's webhook delivery is unreliable—about 3% of payment confirmations are not reaching Zomato's servers, causing failed order confirmations. Your engineering team estimates a fix in 2 weeks. Zomato says they'll escalate to leadership if not resolved in 48 hours.
The call: What do you do in the next 48 hours, and what do you communicate to Zomato?
You are PM for Razorpay's payment APIs. A major enterprise customer (Zomato) reports that the API's webhook delivery is unreliable—about 3% of payment confirmations are not reaching Zomato's servers, causing failed order confirmations. Your engineering team estimates a fix in 2 weeks. Zomato says they'll escalate to leadership if not resolved in 48 hours.
The call: What do you do in the next 48 hours, and what do you communicate to Zomato?
Where to go next
- Understand B2B product dynamics that shape API products: B2B Product Management
- PLG is how most developer products grow: PLG vs Sales-Led
- Working with engineering is your entire job in developer products: Working with Engineering
- Prepare for technical PM interviews at API companies: Technical Questions