PRD Template for API

Example: "We receive an average of 15 integration requests per month from customers who want to connect our product to their internal tools, automate data extraction, or build custom workflows. Currently, each request requires 2-4 weeks of custom engineering work. Three deals in the last quarter stalled because the customer required API access that we could not provide. Our competitor launched a public API 6 months ago and it is cited in 28% of their case studies as a buying factor."

Example: "Primary: 30% of customers actively using the API within 12 months of launch. Secondary: Reduce custom integration engineering from 15 requests/month to under 3. Reliability: 99.9% uptime and p95 latency under 200ms. Developer experience: A developer should be able to make their first successful API call within 15 minutes of reading the documentation."

Example: "As a developer at a customer company, I want to programmatically create and update records via a REST API so that I can sync data between our internal CRM and the product without manual data entry. Acceptance criteria: POST /api/v1/records creates a record and returns the full object with ID; PUT /api/v1/records/:id updates specified fields; responses include standard HTTP status codes; all fields are documented with types and validation rules."

Example: "FR-1: The API must expose CRUD endpoints for all primary resources (users, projects, records, tickets). FR-2: Authentication must use API keys for server-to-server integration and OAuth 2.0 for user-context integrations. FR-3: Rate limiting must be enforced at 1,000 requests per minute per API key, with rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) on every response. FR-4: List endpoints must support cursor-based pagination, with a maximum page size of 100. FR-5: All endpoints must return consistent error responses: { error: { code: string, message: string, details?: object } }."

Example: "NFR-1: The API must maintain 99.9% uptime, measured monthly, with a public status page. NFR-2: p95 response time must be under 200ms for read operations and under 500ms for write operations. NFR-3: The API must support TLS 1.2+ for all requests. NFR-4: API responses must include Cache-Control headers for cacheable resources. NFR-5: All API changes must maintain backward compatibility within a major version. Breaking changes require a new API version with a 12-month deprecation timeline."

Example: "Metric 1: Active API consumers (unique API keys with 1+ call/week). Target: 30% of customers within 12 months. Metric 2: Time to first successful API call. Target: under 15 minutes. Metric 3: API uptime. Target: 99.9%. Metric 4: Custom integration engineering requests. Baseline: 15/month. Target: under 3/month. Metric 5: API error rate (5xx responses / total requests). Target: under 0.1%."

Example: "We will build a REST API following JSON:API conventions for consistency. Authentication uses API keys (passed via X-API-Key header) for server-to-server integration and OAuth 2.0 authorization code flow for user-delegated access. Rate limiting is enforced per API key using a sliding window algorithm backed by Redis. Versioning uses URL path versioning (/api/v1/) with a 12-month deprecation window for major versions. API documentation is auto-generated from OpenAPI 3.0 specs using Redocly."

Example: "Risk: A breaking API change causes customer integrations to fail. Likelihood: High (over the API lifetime). Impact: Critical (customer downtime). Mitigation: Strict versioning policy — no breaking changes within a version. New versions must coexist with old versions for 12 months. Automated backward compatibility tests run on every deploy. Risk: A customer accidentally exposes their API key in a public GitHub repository. Likelihood: High. Impact: High. Mitigation: Implement API key scanning via GitHub Secret Scanning partner program. Support instant key rotation without downtime."