api-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Design — Founder OS

Great APIs are designed before they are built. The contract between frontend and backend — and between your product and other developers — should be explicit, versioned, and stable.

---

## REST API Design Principles

### URL Structure
```
# Resources are nouns, never verbs
GET    /api/v1/users              ✓
GET    /api/v1/getUsers           ✗

# Nested resources show relationships
GET    /api/v1/users/:id/posts    ✓
GET    /api/v1/getUserPosts       ✗

# Actions that don't fit CRUD use sub-resources
POST   /api/v1/users/:id/activate    ✓
POST   /api/v1/activateUser          ✗
```

### HTTP Methods
| Method | Action | Success Code | Body |
|--------|--------|-------------|------|
| GET | Fetch resource(s) | 200 | Response data |
| POST | Create resource | 201 | Created resource |
| PUT | Replace resource | 200 | Updated resource |
| PATCH | Update fields | 200 | Updated resource |
| DELETE | Remove resource | 204 | Empty |

### Standard Response Envelope
```typescript
// Always use this shape — never break it
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;         // Machine-readable: "USER_NOT_FOUND"
    message: string;      // Human-readable: "No user with that ID exists"
    field?: string;       // For validation errors: "email"
  };
  meta?: {
    total: number;        // For paginated lists
    page: number;
    limit: number;
    hasMore: boolean;
  };
}

// Success example
{ "success": true, "data": { "id": "123", "name": "Alice" } }

// Error example
{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Email is invalid", "field": "email" } }

// Paginated list
{ "success": true, "data": [...], "meta": { "total": 500, "page": 2, "limit": 20, "hasMore": true } }
```

### Error Code Standard
```
HTTP 400 — Bad Request      → Validation errors, malformed input
HTTP 401 — Unauthorized     → Not authenticated (no/invalid token)
HTTP 403 — Forbidden        → Authenticated but not permitted
HTTP 404 — Not Found        → Resource doesn't exist
HTTP 409 — Conflict         → Duplicate, state conflict
HTTP 422 — Unprocessable    → Semantically invalid (valid JSON, bad business logic)
HTTP 429 — Too Many Requests → Rate limit hit
HTTP 500 — Internal Error   → Something broke on server side
```

---

## OpenAPI Spec Template

```yaml
openapi: 3.0.3
info:
  title: [Your Product] API
  version: 1.0.0
  description: |
    [Brief description of what this API does]

    ## Authentication
    All endpoints require Bearer token authentication.
    Get a token via POST /api/v1/auth/login

servers:
  - url: https://api.yourproduct.com/v1
    description: Production
  - url: https://api-staging.yourproduct.com/v1
    description: Staging

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      required: [id, email, createdAt]
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        email:
          type: string
          format: email
          example: "alice@example.com"
        name:

From The13thNode/VibeCorp_PromptCEO, MIT.

More from The13thNode/VibeCorp_PromptCEO