Platform Product Manager

## 1. API Design (api)
**Impact:** CRITICAL
**Description:** API design principles, standards, and patterns. The foundation of your developer experience.

## 2. Developer Experience (dx)
**Impact:** CRITICAL
**Description:** Developer onboarding, time-to-value, and overall experience. Your primary differentiator.

## 3. Documentation Strategy (docs)
**Impact:** HIGH
**Description:** Developer documentation structure, quality standards, and maintenance. Docs are product.

## 4. SDK Strategy (sdk)
**Impact:** HIGH
**Description:** SDK and library strategy, language prioritization, and maintenance approaches.

## 5. Versioning & Deprecation (versioning)
**Impact:** HIGH
**Description:** API versioning strategies, breaking change management, and deprecation processes.

## 6. Developer Community (community)
**Impact:** MEDIUM-HIGH
**Description:** Developer community building, engagement, and ecosystem development.

## 7. Integration Marketplace (marketplace)
**Impact:** MEDIUM
**Description:** Partner integrations, marketplace strategy, and ecosystem expansion.

## 8. Platform Metrics (metrics)
**Impact:** CRITICAL
**Description:** Platform health metrics, developer success measurement, and data-driven improvement.


---
title: API Design Principles
impact: CRITICAL
tags: api, design, rest, graphql, standards
---

## API Design Principles

**Impact: CRITICAL**

APIs are user interfaces for developers. Design them with the same rigor and care you'd apply to visual UIs.

### The Five Pillars of API Design

| Pillar | Description | Example |
|--------|-------------|---------|
| **Consistency** | Same patterns everywhere | Always use `created_at` not sometimes `createdAt` |
| **Predictability** | Developers guess correctly | `GET /users/{id}` returns user, not array |
| **Discoverability** | Self-documenting | Clear naming, HATEOAS links |
| **Reliability** | Behaves as expected | Same input = same output |
| **Simplicity** | Easy to understand | Minimal parameters for common cases |

### Resource Naming Conventions

**Good resource naming:**

```
GET    /users                    # List users
GET    /users/{id}               # Get single user
POST   /users                    # Create user
PATCH  /users/{id}               # Update user
DELETE /users/{id}               # Delete user

GET    /users/{id}/orders        # User's orders (nested resource)
GET    /orders/{id}              # Order by ID (top-level access)
```

**Bad resource naming:**

```
GET    /getUsers                 # Verb in URL
GET    /user/{id}                # Inconsistent singular/plural
POST   /users/create             # Redundant action
GET    /users/{id}/getOrders     # Verb in nested resource
GET    /api/v1/Users             # Inconsistent casing
```

### HTTP Methods Matrix

| Method | Idempotent | Safe | Use For |
|--------|------------|------|---------|
| **GET** | Yes | Yes | Reading resources |
| **POST** | No | No | Creating resources, actions |
| **PUT** | Yes | No | Full resource replacement |
| **PATCH** | No* | No | Partial updates |
| **DELETE** | Yes | No | Removing resources |

*PATCH can be idempotent if designed carefully

### Response Envelope Pattern

**Consistent response structure:**

```json
{
  "data": {
    "id": "usr_123",
    "email": "dev@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}
```

**List responses with pagination:**

```json
{
  "data": [
    { "id": "usr_123", "email": "dev1@example.com" },
    { "id": "usr_456", "email": "dev2@example.com" }
  ],
  "meta": {
    "total_count": 150,
    "page": 1,
    "per_page": 20,
    "has_more": true
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=8"
  }
}
```

### Error Response Design

**Good error responses:**

```json
{
  "error": {
    "code": "validation_error",
    "message": "The request body contains invalid fields",
    "details": [