Framework

API specs are PRDs for backend. Specify:

  • Endpoints: List all (GET /users, POST /recommendations, etc.)
  • Request format: What parameters, data types, defaults
  • Response format: Success (200), failures (400, 404, 500), example JSON
  • Authentication: How do you authenticate requests?
  • Rate limits: Calls per second/hour per user
  • Versioning: How do you handle API changes?

Example:

GET /recommendations?user_id=123&limit=10

Response (200):
{
  "recommendations": [
    {"id": "456", "title": "...", "confidence": 0.87}
  ],
  "timestamp": "2026-04-15T10:00:00Z"
}

Errors (400, 404, 429): Documented
Rate limit: 100 calls/minute per user

Why PMs Avoid API Specs (And Why They Shouldn't)

PM mindset: "API specs are for engineers. I write feature specs."

Reality: API specs prevent integration disasters.

Real-world scenario:

Integration team starts building:

  • Calls /recommendations?user_id=123
  • Expects {"recommendations": [...]}
  • Actually gets {"data": [...]}
  • Field name mismatch costs 2 days debugging

PM lesson: API spec would have prevented this in 30 minutes.

Framework: The Essential API Spec (Not the 50-Page Version)

Part 1: Endpoint List

ENDPOINT: GET /recommendations

Purpose: Fetch personalized product recommendations for a user

METHOD: GET
ROUTE: /recommendations
PARAMETERS:
  - user_id (required): User ID (integer)
  - limit (optional): Number of recommendations (default: 10, max: 100)
  - exclude_categories (optional): Categories to exclude (comma-separated string)

RESPONSE (200 OK):
{
  "recommendations": [
    {
      "id": "product_456",
      "title": "Wireless Headphones",
      "confidence": 0.87,
      "category": "Electronics",
      "price": 99.99
    }
  ],
  "timestamp": "2026-04-15T10:00:00Z",
  "generated_at_ms": 145
}

ERRORS:
  - 400 Bad Request: Missing user_id or invalid limit
  - 401 Unauthorized: Invalid API key
  - 429 Too Many Requests: Rate limit exceeded (100 req/min per user)
  - 500 Internal Server Error: Unexpected error

RATE LIMIT:
- 100 requests per minute per user
- Returns 429 if exceeded
- Reset time in response header: X-RateLimit-Reset

VERSIONING:
- Current: v1
- Backward-incompatible changes → v2
- Deprecated endpoints removed after 6 months notice

Part 2: Request/Response Contract

REQUEST CONTRACT:

GET /recommendations?user_id=123&limit=5&exclude_categories=Furniture,Decor

- user_id: Integer, required
- limit: Integer, optional (default 10, max 100)
- exclude_categories: String (comma-separated), optional

RESPONSE CONTRACT (Success):

{
  "recommendations": [
    {
      "id": string (product ID),
      "title": string (product name),
      "confidence": number (0.0-1.0, how confident is this recommendation),
      "category": string (product category),
      "price": number (USD, 2 decimals),
      "url": string (product link)
    }
  ],
  "timestamp": string (ISO 8601),
  "generated_at_ms": number (how long to generate these recommendations)
}

RESPONSE CONTRACT (Error):

{
  "error": string (error message),
  "error_code": string (e.g., "RATE_LIMIT_EXCEEDED"),
  "timestamp": string (ISO 8601)
}

Part 3: Authentication & Security

AUTHENTICATION: API Key

Every request must include:
Authorization: Bearer YOUR_API_KEY

Example:
curl -H "Authorization: Bearer sk_live_abc123" https://api.pmsynapse.com/recommendations?user_id=123

RATE LIMITING:

Per user: 100 requests/minute
Per API key: 10,000 requests/day

Rate limit headers:
- X-RateLimit-Limit: 100
- X-RateLimit-Remaining: 87
- X-RateLimit-Reset: 1681656000

ERRORS:
- 401 Unauthorized: Invalid/missing API key
- 429 Too Many Requests: Rate limit exceeded

VERSIONING: v1 (current), v2 (planned, EOY 2026)

Real-World Example: API Spec Preventing Integration Failures

Scenario: Third-Party Integrating Recommendations API

Bad API Spec (Vague):

ENDPOINT: /recommendations

Returns: List of recommended products

Integrators had to guess:
- What are the fields in each product?
- What's the confidence score range?
- How fast is the API?
- What happens if user_id doesn't exist?
- Can I call it 1000 times/second?

Result: 3 integration attempts, 2 failed in production, 4 weeks of back-and-forth.

Good API Spec (Specific):

ENDPOINT: GET /recommendations?user_id=ID&limit=N

RESPONSE:
{
  "recommendations": [
    {"id": "prod_123", "title": "...", "confidence": 0.87}
  ],
  "timestamp": "2026-04-15T...",
  "generated_at_ms": 145
}

RATE LIMIT: 100 req/min per user

ERRORS:
- 400: Missing user_id
- 404: User not found
- 429: Rate limit exceeded

Integrators got it right on first try. Shipped in 2 weeks. Zero production issues.

Anti-Pattern: "We'll Figure Out the API During Integration"

The Problem:

  • PM: "Don't spec the API. We'll figure it out as integrations happen."
  • Integrations start: Each one has different assumptions
  • Production: Inconsistencies and failures
  • Rework: Every integrator has to adapt their code

The Fix:

  • Spec the API in the PRD (30 minutes)
  • Share spec before engineering builds
  • Integrations use consistent contract

Actionable Steps

Step 1: List All Endpoints

Endpoints for Recommendations Feature:

1. GET /recommendations (fetch user recommendations)
2. POST /recommendations/feedback (user thumbs up/down)
3. GET /recommendations/debug (show model confidence, for testing)

Step 2: Spec Each Endpoint

For every endpoint:

ENDPOINT: [Name]
METHOD: [GET/POST/PUT/DELETE]
ROUTE: [/path]

PARAMETERS: [List with types + required/optional]

RESPONSE: [Example JSON]

ERRORS: [Possible status codes + meanings]

RATE LIMIT: [Requests per minute]

Step 3: Define Error Responses

Every error should include:

{
  "error": string (human-readable message),
  "error_code": string (machine-readable code),
  "timestamp": string (ISO 8601)
}

Examples:
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 429 Too Many Requests
- 500 Internal Server Error

Step 4: Specify Rate Limiting

Per user: X requests/minute
Per API key: Y requests/day
Per IP: Z requests/minute (optional)

Include rate limit headers in response:
- X-RateLimit-Limit
- X-RateLimit-Remaining
- X-RateLimit-Reset

Step 5: Plan for Versioning

VERSION: v1 (current)

BACKWARD COMPATIBILITY:
- Field additions: OK (integrators ignore new fields)
- Field removal: Not OK (breaks integrators)
- Parameter change: Not OK (needs new endpoint)

DEPRECATION POLICY:
- Announce deprecated endpoints 6 months before removal
- Support old version during transition period

PMSynapse Connection

API specs are tedious but critical. PMSynapse's API Spec Generator reads your feature description and generates a spec template: "You're building recommendations. Here's the endpoint, request/response contract, rate limiting, and versioning spec." By automating API spec generation, PMSynapse ensures integrations are never guessing.

Key Takeaways

  • API specs prevent integration disasters. Clear contract = faster, fewer bugs.

  • Spec doesn't have to be 50 pages. 5 things: Endpoint list + Request/Response contract + Auth + Rate limit + Versioning.

  • Field names matter. {"recommendations": [...]} vs. {"data": [...]} causes 2-day debugging sessions. Spec prevents it.

  • Rate limiting is part of the spec. Don't surprise integrators with 429 errors. Tell them the limits upfront.

  • Version from day one. Retrofitting versioning later is expensive. Plan for it upfront.

API Specification for PMs: What You Need to Know (And What You Don't)

Article Type

SPOKE Article — Links back to pillar: /prd-writing-masterclass-ai-era

Target Word Count

2,500–3,500 words

Writing Guidance

Cover: the PM's role in API specification (what vs. how), contract-first design, and understanding API concepts without engineering them. Soft-pitch: PMSynapse's Feature-to-Feasibility Translator helps PMs specify API-level contracts.

Required Structure

1. The Hook (Empathy & Pain)

Open with an extremely relatable, specific scenario from PM life that connects to this topic. Use one of the PRD personas (Priya the Junior PM, Marcus the Mid-Level PM, Anika the VP of Product, or Raj the Freelance PM) where appropriate.

2. The Trap (Why Standard Advice Fails)

Explain why generic advice or common frameworks don't address the real complexity of this problem. Be specific about what breaks down in practice.

3. The Mental Model Shift

Introduce a new framework, perspective, or reframe that changes how the reader thinks about this topic. This should be genuinely insightful, not recycled advice.

4. Actionable Steps (3-5)

Provide concrete actions the reader can take tomorrow morning. Each step should be specific enough to execute without further research.

5. The Prodinja Angle (Soft-Pitch)

Conclude with how PMSynapse's autonomous PM Shadow capability connects to this topic. Keep it natural — no hard sell.

6. Key Takeaways

3-5 bullet points summarizing the article's core insights.

Internal Linking Requirements

  • Link to parent pillar: /blog/prd-writing-masterclass-ai-era
  • Link to 3-5 related spoke articles within the same pillar cluster
  • Link to at least 1 article from a different pillar cluster for cross-pollination

SEO Checklist

  • Primary keyword appears in H1, first paragraph, and at least 2 H2s
  • Meta title under 60 characters
  • Meta description under 155 characters and includes primary keyword
  • At least 3 external citations/references
  • All images have descriptive alt text
  • Table or framework visual included