API Design Prompt Templates

## Subscription API Endpoints

### Create Subscription
`POST /api/v1/subscriptions`

**Request:**
```json
{
 "plan_id": "plan_pro_monthly",
 "payment_method_id": "pm_xxx"
}
```

**Response (201 Created):**
```json
{
 "id": "sub_abc123",
 "plan": { "id": "plan_pro_monthly", "name": "Pro Monthly" },
 "status": "active",
 "current_period_end": "2024-02-15T00:00:00Z",
 "cancel_at_period_end": false
}
```

### List Subscription History
`GET /api/v1/subscriptions`

**Query params:**
- `status` - Filter by: active, canceled, past_due
- `limit` - Max 100, default 20
- `starting_after` - Cursor for pagination

**Response (200):**
```json
{
 "data": [...],
 "has_more": true,
 "next_cursor": "sub_xyz789"
}
```

### Change Plan
`PATCH /api/v1/subscriptions/{id}`

**Request:**
```json
{
 "plan_id": "plan_enterprise_monthly",
 "proration_behavior": "create_prorations"
}
```

### Cancel Subscription
`DELETE /api/v1/subscriptions/{id}?cancel_at_period_end=true`

**Response (200):** Returns subscription with `cancel_at_period_end: true`

## Error Response Structure

**Standard format:**
```json
{
 "error": {
 "code": "VALIDATION_ERROR",
 "message": "The request could not be processed due to validation errors.",
 "details": [...],
 "request_id": "req_abc123"
 }
}
```

### Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| VALIDATION_ERROR | 400 | Request body/params invalid |
| UNAUTHORIZED | 401 | Missing or invalid auth |
| FORBIDDEN | 403 | Valid auth, insufficient permissions |
| NOT_FOUND | 404 | Resource doesn't exist |
| RATE_LIMITED | 429 | Too many requests |
| INTERNAL_ERROR | 500 | Server error (don't expose details) |

### Validation Errors (with field details)
```json
{
 "error": {
 "code": "VALIDATION_ERROR",
 "message": "Please fix the following errors.",
 "details": [
 {
 "field": "email",
 "code": "INVALID_FORMAT",
 "message": "Please enter a valid email address."
 },
 {
 "field": "password",
 "code": "TOO_SHORT",
 "message": "Password must be at least 8 characters."
 }
 ]
 }
}
```

### Rate Limit Response
```json
{
 "error": {
 "code": "RATE_LIMITED",
 "message": "Too many requests. Please try again in 60 seconds.",
 "retry_after": 60
 }
}
```

**Headers for rate limits:**
- `X-RateLimit-Limit: 100`
- `X-RateLimit-Remaining: 0`
- `X-RateLimit-Reset: 1705312800`

## Recommended Strategy: URL Path Versioning

Given your external partners with slow update cycles, URL path versioning (`/api/v1/`, `/api/v2/`) provides:
- Clear visual distinction between versions
- Easy for partners to test against both versions
- Simple routing in your infrastructure

### Deprecation Policy

1. **Announce** new version 3 months before release
2. **Sunset warning** on old version: 6 months after new version launches
3. **Deprecation headers** immediately on old version:
 ```
 Deprecation: true
 Sunset: Sat, 15 Jun 2025 00:00:00 GMT
 Link: <https://api.example.com/v2/orders>; rel="successor-version"
 ```
4. **Hard deprecation** 9 months after new version (12 months total support)

### Migration Strategy for Order Resource

**Phase 1:** Release v2 with new order structure
- v1 and v2 run in parallel
- v1 responses include deprecation headers

**Phase 2:** Provide migration helper
- `GET /api/v1/orders/{id}?include=v2_preview` returns both formats
- Detailed migration guide with field mappings

**Phase 3:** Usage monitoring
- Track v1 usage by partner
- Reach out to high-volume v1 users at 3-month mark

### Communication Plan

1. Email announcement to all API key holders
2. In-dashboard banner for developer portal
3. Changelog with detailed field-by-field migration guide
4. Office hours / Q&A sessions for partners

```graphql
type User {
 id: ID!
 name: String!
 email: String!
 posts(first: Int, after: String): PostConnection!
}

type Post {
 id: ID!
 slug: String!
 title: String!
 content: String!
 author: User!
 comments(first: Int = 20, after: String): CommentConnection!
 commentCount: Int! # Denormalized for performance
 createdAt: DateTime!
 updatedAt: DateTime!
}

type Comment {
 id: ID!
 content: String!
 author: User!
 createdAt: DateTime!
}

# Relay-style pagination
type PostConnection {
 edges: [PostEdge!]!
 pageInfo: PageInfo!
 totalCount: Int!
}

type PostEdge {
 node: Post!
 cursor: String!
}

type Query {
 post(id: ID, slug: String): Post
 posts(
 first: Int = 20
 after: String
 filter: PostFilter
 orderBy: PostOrder = CREATED_AT_DESC
 ): PostConnection!
}

input PostFilter {
 authorId: ID
 publishedAfter: DateTime
 search: String
}

type Mutation {
 createPost(input: CreatePostInput!): CreatePostPayload!
 updatePost(id: ID!, input: UpdatePostInput!): UpdatePostPayload!
 deletePost(id: ID!): DeletePostPayload!
 addComment(postId: ID!, input: AddCommentInput!): AddCommentPayload!
}

input CreatePostInput {
 title: String!
 content: String!
 slug: String # Auto-generated if not provided
}

type CreatePostPayload {
 post: Post
 errors: [UserError!]!
}
```

**Resolver Notes:**
- `Post.comments`: Use DataLoader to batch comment fetches across posts
- `Post.commentCount`: Store denormalized, update via database trigger
- `posts` query: Implement cursor-based pagination with Relay spec