What makes an API PRD different from a feature PRD?

An API PRD focuses on developer personas rather than end users, endpoint contracts rather than UI flows, authentication and rate limiting rather than UX, versioning and deprecation policy rather than feature toggles, and SLA commitments rather than conversion metrics. The failure modes are also different: the primary failure is a breaking change that silently corrupts downstream integrations, not a poor user experience.

Should I use URL versioning or header versioning for my API?

URL versioning (/v1/, /v2/) is the industry standard for public APIs because it is explicit, cache-friendly, and easy to route at the infrastructure level. Header versioning (Accept: application/vnd.api.v2+json) is harder to test and more error-prone. Use URL versioning for any externally-facing API. Header versioning is defensible only for internal APIs where you control all consumers.

What constitutes a breaking API change?

Breaking changes include: removing an endpoint, removing a required or optional response field, changing a field's data type (including narrowing a string to an enum), changing the meaning of an error code, and changing authentication requirements. Non-breaking (additive) changes include: adding new endpoints, adding new optional request fields, adding new optional response fields, and adding new error codes. Document this policy in your PRD before you ship your first version.

How long should an API deprecation window be?

The industry standard for externally-facing APIs is 12 months from deprecation announcement to endpoint removal. Stripe uses 12 months. Twilio uses 12 months. For high-traffic APIs with many integrators, 18 months is safer. For internal APIs with known consumers, 3–6 months is acceptable if all consumers are notified directly and have migration support.

What rate limits should I set for a new API?

Start conservative: 10 requests/minute for free tier, 100 requests/minute for paid tier. These numbers are easy to raise — they are very hard to lower without breaking existing integrations. Monitor actual usage patterns in the first 30 days. The most common API rate limit mistake is setting limits too high initially and then needing to enforce lower limits on existing integrators.

API PRD Template for Developer Products

An API PRD template must include developer personas, endpoint contracts, authentication flows, versioning strategy, rate limits, error codes, and SLA commitments. Generic PRD templates omit every one of these sections. The template below is structured for REST APIs; adapt section 3 for GraphQL or gRPC as needed.

43%

of API support tickets caused by undocumented error codes

67%

of developer API abandonment in first 30 minutes due to auth friction

Why API PRDs need their own template

A developer product has a different primary persona (a developer, not an end user), a different success metric (integration success rate, time-to-first-successful-call), and a different failure mode (a breaking change that silently corrupts downstream integrations). None of these appear in a standard consumer-product PRD template.

The most expensive API failure is an undocumented breaking change. The second most expensive is an auth flow that takes longer than 30 minutes to complete. Both are preventable with a PRD that asks the right questions before a single endpoint is designed.

The API PRD template

1. Developer persona

Primary: Backend engineer at a SaaS company integrating [your product] into their existing workflow. Comfortable with REST APIs, OAuth 2.0, and JSON. Expects OpenAPI spec and a working Postman collection. Does not want to read prose documentation to understand what an endpoint does.

Secondary: Solo developer / indie hacker building a side project. May be less familiar with enterprise auth flows. Needs a quick-start guide that produces a working API call in under 10 minutes.

2. Objective

Example: Launch a REST API for [resource] that enables developers to [primary action] and [secondary action], with a target of under 10 minutes from API key creation to first successful authenticated request.

3. Endpoint contracts

For each endpoint, specify: method, path, authentication required, request body schema, response schema, and error responses. Do not leave schemas to engineering to define — define them in the PRD.

POST /v1/prds

Auth: Bearer token (API key). Rate limit: 100 requests/min per API key.

Request body: {"input": "string (required, max 10,000 chars)", "format": "markdown | json (optional, default: json)"}

Response 201: {"id": "string", "status": "generating | complete", "prd": {...} | null, "created_at": "ISO 8601"}

Response 400: Invalid input — {"error": "invalid_input", "message": "input exceeds 10,000 character limit"}

Response 429: Rate limit exceeded — {"error": "rate_limit_exceeded", "retry_after": 60}

4. Authentication flow

Auth method: API key (Bearer token in Authorization header). OAuth 2.0 for workspace-level access (v2, out of scope for this release).

Key creation: Self-serve via dashboard. Instant provisioning. No approval flow for standard tier.

Key scopes: read (GET endpoints), write (POST/PATCH/DELETE), admin (key management). Keys created with write scope by default.

Key rotation: User-initiated. Old key active for 24-hour grace period after rotation. Webhook notification on key rotation.

Time to first successful call target: Under 10 minutes from account creation to authenticated API response.

5. Versioning strategy

Version in URL path: /v1/ prefix. New major versions on breaking changes only.

Deprecation policy: Minimum 12-month deprecation window for any v1 endpoint. Email notification to all active API key holders 90 days before deprecation. Migration guide published at deprecation announcement.

What constitutes a breaking change: Removing an endpoint, removing a required or optional response field, changing a field's data type, changing an error code's meaning. Additive changes (new optional fields, new endpoints) are non-breaking and do not require a version bump.

6. Rate limits

Tier Requests / minute Requests / day Response on exceed

Free 10 100 429 + Retry-After header

Pro 100 5,000 429 + Retry-After header

Enterprise Custom Custom 429 + Retry-After header

Rate limit headers returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp).

Tier	Requests / minute	Requests / day	Response on exceed
Free	10	100	429 + Retry-After header
Pro	100	5,000	429 + Retry-After header
Enterprise	Custom	Custom	429 + Retry-After header

7. Error codes

Document every error code before engineering builds. Undocumented error codes are the leading cause of API support tickets.

HTTP status Error code Meaning Developer action

400 invalid_input Request body fails validation Check message field for specific validation error

401 unauthorized Missing or invalid API key Check Authorization header format: Bearer [key]

403 insufficient_scope API key lacks required scope Create a new key with write scope

404 not_found Resource does not exist Verify the resource ID in the path

429 rate_limit_exceeded Rate limit hit Wait retry_after seconds and retry

500 internal_error Unexpected server error Retry with exponential backoff; contact support if persistent

503 service_unavailable Planned maintenance or capacity Check status page; retry after Retry-After header value

HTTP status	Error code	Meaning	Developer action
400	invalid_input	Request body fails validation	Check message field for specific validation error
401	unauthorized	Missing or invalid API key	Check Authorization header format: Bearer [key]
403	insufficient_scope	API key lacks required scope	Create a new key with write scope
404	not_found	Resource does not exist	Verify the resource ID in the path
429	rate_limit_exceeded	Rate limit hit	Wait retry_after seconds and retry
500	internal_error	Unexpected server error	Retry with exponential backoff; contact support if persistent
503	service_unavailable	Planned maintenance or capacity	Check status page; retry after Retry-After header value

8. SLA commitments

Uptime SLA: 99.9% monthly (Pro and Enterprise). Calculated as: (total minutes − downtime minutes) / total minutes.

Latency SLA: p95 response time under 500ms for synchronous endpoints. Async generation endpoints excluded from latency SLA; status polling endpoint (GET /v1/prds/{id}) included.

Status page: status.scriptonia.dev. Webhooks available for incident notifications.

9. Developer experience requirements

OpenAPI 3.1 spec published at /openapi.json and /openapi.yaml before launch.

Postman collection with pre-configured auth and example requests for all endpoints.

Quick-start guide: 5 steps, working code example in JavaScript and Python, reaches first successful API call in under 10 minutes for a developer reading for the first time.

Changelog: versioned changelog published with every API update. Format: date, affected endpoints, change type (breaking / additive / fix).