Platform & API Product Management

REST API Design Review Core Method

Use when: designing new endpoints or reviewing existing API surface area.

A well-designed REST API follows predictable patterns: resources as nouns (/users, /orders), HTTP methods as verbs (GET, POST, PUT, DELETE), consistent naming conventions (plural nouns, kebab-case), and standard status codes (200, 201, 400, 404, 422, 500). The PM's job isn't writing the OpenAPI spec — it's ensuring the API models the domain correctly. If your mental model of the domain is wrong, the API will be wrong, and every developer who integrates will fight the abstraction.

Review every endpoint against three questions: (1) Does this resource name match how developers think about the domain? (2) Can a developer guess what this endpoint does without reading docs? (3) Is the response shape consistent with every other endpoint? If any answer is no, redesign before shipping.

GraphQL vs. REST Decision Framework Framework

Use when: choosing API paradigm for a new product or major version.

REST works well when your domain has clear, stable resources and consumers need predictable, cacheable responses. GraphQL works well when consumers need flexible queries across related data, when mobile bandwidth matters (no over-fetching), or when your frontend team and backend team want to decouple iteration speed. gRPC works well for internal service-to-service communication where performance matters more than developer ergonomics.

The decision isn't purely technical — it's a product decision. GraphQL shifts complexity to consumers (they write queries). REST shifts complexity to providers (they design endpoints for every use case). Choose based on who you trust more to handle complexity: your team or your developers.

Time-to-First-API-Call (TTFAC) Optimization Core Method

Use when: evaluating or improving your onboarding funnel.

TTFAC is the single most important DX metric. It measures how long it takes a new developer to go from landing on your docs to successfully making their first API call. Best-in-class platforms achieve this in under 5 minutes. If yours takes 30 minutes or more, you're losing developers at every step.

Map the current TTFAC journey: (1) Find documentation → (2) Create account → (3) Get API key → (4) Install SDK → (5) Write first call → (6) Get successful response. Time each step. The biggest time sinks are usually account creation (too many fields), API key generation (buried in settings), and unclear quickstart guides (too much context, not enough copy-paste code).

Optimize ruthlessly: offer one-click sandbox keys, provide copy-pasteable curl commands on the landing page, auto-detect the developer's language and show the right SDK example, and make error messages actionable ("Invalid API key — generate one at dashboard.example.com/keys").

Documentation Audit Technique

Use when: docs exist but developer satisfaction is low or support tickets are high.

Great API docs have four layers:

1. Tutorials — guided walkthroughs for common tasks ("Send your first SMS"),.
2. How-to guides — task-oriented recipes ("Handle webhook retries"),.
3. Reference — complete endpoint documentation with every parameter,.
4. Explanation — conceptual overviews of how the system works ("How our event system processes webhooks"). Most API docs only have layer 3 (reference). That's like having a dictionary but no grammar book — technically complete, practically useless for learning.

Audit by tagging every doc page as tutorial, how-to, reference, or explanation. If any layer has fewer than 20% of pages, that's your gap. Then interview 5 developers who recently integrated: what did they struggle with? The overlap between the structural gap and developer pain points is your documentation roadmap.

SDK Strategy Matrix Framework

Use when: deciding which languages to support and how to maintain SDKs.

Start with your developer telemetry: which languages are developers using to call your API? Rank by volume. Then decide your SDK tier: Tier 1 (official, maintained, feature-complete) for your top 2-3 languages, Tier 2 (community-maintained with your review) for the next 3-4, Tier 3 (community-only, listed but not endorsed) for the rest. Never promise official support for more languages than your team can realistically maintain — a broken SDK is worse than no SDK.

Consider auto-generation from your OpenAPI spec (tools like openapi-generator, Stainless, Fern) for Tier 1 SDKs. This ensures SDKs stay in sync with your API automatically. The PM decision is whether to invest in hand-crafted SDKs (better DX, higher maintenance cost) or auto-generated ones (lower maintenance, sometimes awkward ergonomics).

API Versioning Strategy Core Method

Use when: planning your first major version bump or establishing versioning policy.

There are three common approaches: URL versioning (/v1/users, /v2/users) — simple, visible, but creates duplicate endpoints; header versioning (API-Version: 2024-01-15) — clean URLs but less discoverable; date-based versioning (Stripe's approach: Stripe-Version: 2024-06-20) — each API key pins to the version it was created on, and developers opt into upgrades explicitly.

The PM decision isn't which mechanism to use — it's what your compatibility promise is. How long will you support old versions? (Stripe: indefinitely. Most APIs: 12-24 months.) What constitutes a breaking change? (Removing a field: always breaking. Adding a field: usually not. Changing a field type: always breaking. Changing default behavior: breaking.) Document your compatibility policy publicly and hold yourself to it. Breaking changes without warning destroy developer trust faster than any bug.

Deprecation Playbook Technique

Use when: you need to sunset an old API version or endpoint.

Follow this sequence: (1) Announce deprecation 6+ months before sunset, (2) Add deprecation headers to responses (Deprecation: true, Sunset: 2025-06-01), (3) Email all developers using the deprecated endpoint (use your API logs to identify them), (4) Provide a migration guide with before/after code examples, (5) Offer migration support (office hours, dedicated Slack channel), (6) Send final warning 30 days before sunset, (7) Return 410 Gone after sunset date with a link to the migration guide. Never silently break an endpoint. Even if only 12 developers still use it, those 12 developers built their business on your promise.

Developer Funnel Analysis Framework

Use when: measuring ecosystem health and identifying growth bottlenecks.

Map your developer funnel: Awareness (heard of your API) → Registration (created an account) → First call (made a successful API call) → Integration (shipped a production integration) → Expansion (using multiple endpoints or higher volume) → Advocacy (recommending your API to others). Track conversion rates between each stage. The biggest drop usually happens between Registration and First Call — that's your TTFAC problem. The second biggest is between First Call and Integration — that's a documentation or reliability problem.

Partner Tier Framework Framework

Use when: structuring relationships with ecosystem partners.

Create tiers based on mutual value:

• Self-serve — anyone can integrate using public docs, no relationship needed.
• Technology partners — companies building maintained integrations, get early access to beta APIs and co-marketing.
• Strategic partners — deep integrations that drive significant mutual revenue, get dedicated engineering support and joint roadmap planning. Most ecosystems are 90% self-serve, 8% technology, 2% strategic. Don't over-invest in partner management for self-serve developers — invest in documentation and tooling instead.