api-integration

# API Integration — Expert Decisions

Expert decision frameworks for API integration choices. Claude knows URLSession and Codable — this skill provides judgment calls for architecture decisions and caching strategies.

---

## Decision Trees

### REST vs GraphQL

```
What's your data access pattern?
├─ Fixed, well-defined endpoints
│  └─ REST
│     Simpler caching, HTTP semantics
│
├─ Flexible queries, varying data needs per screen
│  └─ GraphQL
│     Single endpoint, client specifies shape
│
├─ Real-time subscriptions needed?
│  └─ GraphQL subscriptions or WebSocket + REST
│     GraphQL has built-in subscription support
│
└─ Offline-first with sync?
   └─ REST is simpler for conflict resolution
      GraphQL mutations harder to replay
```

**The trap**: Choosing GraphQL because it's trendy. If your API has stable endpoints and you control both client and server, REST is simpler.

### API Versioning Strategy

```
How stable is your API?
├─ Stable, rarely changes
│  └─ No versioning needed initially
│     Add when first breaking change occurs
│
├─ Breaking changes expected
│  └─ URL path versioning (/v1/, /v2/)
│     Most explicit, easiest to manage
│
├─ Gradual migration needed
│  └─ Header versioning (Accept-Version: v2)
│     Same URL, version negotiated
│
└─ Multiple versions simultaneously
   └─ Consider if you really need this
      Maintenance burden is high
```

### Caching Strategy Selection

```
What type of data?
├─ Static/rarely changes (images, config)
│  └─ Aggressive cache (URLCache + ETag)
│     Cache-Control: max-age=86400
│
├─ User-specific, changes occasionally
│  └─ Cache with validation (ETag/Last-Modified)
│     Always validate, but use cached if unchanged
│
├─ Frequently changing (feeds, notifications)
│  └─ No cache or short TTL
│     Cache-Control: no-cache or max-age=60
│
└─ Critical real-time data (payments, inventory)
   └─ No cache, always fetch
      Cache-Control: no-store
```

### Offline-First Architecture

```
How important is offlin