Writing CLAUDE.md Files That Define Your Project's API

When working with AI coding assistants on API-driven projects, consistent versioning behavior becomes critical. A well-crafted CLAUDE.md file ensures your AI assistant understands and respects your API versioning strategy, preventing breaking changes, maintaining backward compatibility, and following your team’s conventions. This guide shows you how to document API versioning strategies in CLAUDE.md files for optimal AI-assisted development.

Why API Versioning Belongs in CLAUDE.md

Your API versioning strategy affects every endpoint, request, and response in your project. Without explicit instructions, AI assistants may generate inconsistent endpoint paths, ignore version headers, or fail to implement proper deprecation warnings. By documenting your versioning approach in CLAUDE.md, you establish a source of truth that guides every code generation decision.

AI assistants excel at following explicit patterns. When you define your versioning strategy clearly, they generate versioned endpoints correctly from the start, implement proper deprecation cycles, and maintain consistent header handling across your codebase.

Structuring Your API Versioning Documentation

An API versioning section in CLAUDE.md should cover several key areas. Start with your versioning scheme choice, then detail URL structure, header requirements, deprecation policies, and response format standards.

Versioning Scheme Definition

Begin by clearly stating which versioning approach your project uses. Common options include URL path versioning, header versioning, or query parameter versioning. Here’s how to document each:

## API Versioning Strategy

### Versioning Scheme
- URL Path Versioning: `/api/v1/users`, `/api/v2/users`
- Header Versioning: `Accept: application/vnd.myapp.v1+json`
- Query Parameter: `/api/users?version=1`

Our project uses: URL Path Versioning (v1, v2, v3)

Endpoint Versioning Rules

Specify how endpoints should be versioned and which patterns to follow:

### Endpoint Versioning Rules
- All versioned endpoints MUST include version in URL path: `/api/v{version}/`
- Version number starts at 1 and increments with each breaking change
- Latest stable version: v2 (as of March 2026)
- Deprecated versions remain supported for 12 months after deprecation announcement
- All v1 endpoints will be sunset on December 31, 2026

Header and Request Handling

Document required headers and how the AI should handle version negotiation:

### Request Headers
- Required: `Content-Type: application/json`
- Version header (optional for URL path): `X-API-Version: 2`
- Rate limiting header: `X-RateLimit-Limit`

### Response Headers
- Always include: `X-API-Version` showing the version that processed the request
- Deprecation warnings: `Deprecation: true`, `Sunset: Sat, 01 Jan 2027 00:00:00 GMT`

Practical Implementation Patterns

Beyond documentation, your CLAUDE.md should include concrete code patterns that the AI can reference when generating new endpoints.

Versioned Endpoint Template

// When creating new endpoints, use this structure:
// GET /api/v{version}/{resource}

interface ApiResponse<T> {
  data: T;
  version: number;
  meta?: {
    deprecated?: boolean;
    sunsetDate?: string;
    migrationGuide?: string;
  };
}

// Example v2 user endpoint with backward-compatible response
app.get('/api/v2/users/:id', (req, res) => {
  const user = getUser(req.params.id);

  res.json({
    data: {
      id: user.id,
      email: user.email,
      // v2 adds profile field not present in v1
      profile: {
        avatar: user.avatarUrl,
        bio: user.bio
      }
    },
    version: 2,
    meta: user.isDeprecated ? {
      deprecated: true,
      sunsetDate: '2026-12-31',
      migrationGuide: '/docs/v2-migration'
    } : undefined
  });
});

Deprecation Warning Pattern

// Implement deprecation warnings for older versions
function addDeprecationHeaders(res: Response, version: number) {
  if (version === 1) {
    res.setHeader('Deprecation', 'true');
    res.setHeader('Sunset', 'Sat, 01 Jan 2027 00:00:00 GMT');
    res.setHeader('Link', '</api/v2/users>; rel="successor-version"');
  }
}

Version-Specific Response Handling

Your CLAUDE.md should specify how the AI should handle responses differently across versions:

### Response Versioning Strategy

#### Version 1 (Deprecated)
- Basic user object with only: id, email, name
- No nested objects
- Limited metadata

#### Version 2 (Current Stable)
- Extended user object: id, email, name, profile, preferences
- Includes nested preference object
- Full metadata support

#### Version 3 (Beta)
- All v2 fields plus: analytics, activityLog
- Cursor-based pagination
- Real-time subscriptions via WebSocket

### Generating Versioned Code
When adding new features, follow these rules:
1. New features go in the latest stable version (v2)
2. Breaking changes require new version (v3)
3. Non-breaking additions can be backported to active versions
4. Always maintain backward compatibility within major versions

Migration and Backward Compatibility

Include clear guidance on how to handle migrations between versions:

## API Migration Guidelines

### Adding New Fields
- New fields are optional in responses
- Never remove fields from existing versions
- Document new optional fields clearly

### Changing Field Types
- If changing a field type, introduce new field name
- Keep old field for backward compatibility
- Mark old field as deprecated in documentation

### Removing Endpoints
- Announce deprecation 6 months in advance
- Continue supporting for 12 months minimum
- Provide clear migration path in response headers

Testing Versioned Endpoints

Your CLAUDE.md should also specify testing requirements for versioned APIs:

### Testing Requirements

1. **Version Coverage**: Test each active version endpoint
2. **Backward Compatibility**: Ensure vN+1 responses include all vN fields
3. **Deprecation Headers**: Verify Sunset and Deprecation headers appear correctly
4. **Version Negotiation**: Test both URL path and header-based versioning

### Test Example
```typescript
describe('API v1 deprecation', () => {

 it('should include deprecation headers', async () => {

 const response = await request(app).get('/api/v1/users/1');

 expect(response.headers['deprecation']).toBe('true');

 expect(response.headers['sunset']).toBeDefined();

 });

});

```

Common Pitfalls to Avoid

When documenting your API versioning strategy, watch for these common mistakes that confuse AI assistants:

Avoid vague version descriptions. Instead of “use appropriate versioning,” specify exactly which versioning method your project uses.

Don’t skip deprecation policies. Without clear sunset dates and migration guides, AI-generated code won’t include proper deprecation handling.

Include concrete examples. Abstract descriptions fail; real code patterns work. Show exactly what a versioned endpoint should look like in your language and framework.

Specify response differences explicitly. AI assistants need to know what fields exist in each version to generate correct code.

Built by theluckystrike — More at zovo.one