# API Changelog

## Version 3.0.0 - 2025-01-15

### 🚨 Breaking Changes

#### Authentication Method Changed

**Previous (v2):**
```http
GET /api/users
Authorization: Token abc123

GET /api/v3/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com"
}

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

// Before (v2)
const user = await response.json();
console.log(user.name);

// After (v3)
const { data } = await response.json();
console.log(data.attributes.name);

// Or use our SDK which handles this automatically
import { ApiClient } from '@company/api-sdk';
const user = await client.users.get('123');
console.log(user.name); // SDK unwraps the response

POST /api/v3/webhooks
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "events": ["user.created", "user.updated", "user.deleted"],
  "secret": "your-webhook-secret"
}

{
  "event": "user.created",
  "timestamp": "2025-01-15T14:30:00Z",
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

POST /api/v3/users/batch
Content-Type: application/json

{
  "operations": [
    {
      "method": "POST",
      "path": "/users",
      "body": { "name": "User 1", "email": "user1@example.com" }
    },
    {
      "method": "PATCH",
      "path": "/users/123",
      "body": { "name": "Updated Name" }
    },
    {
      "method": "DELETE",
      "path": "/users/456"
    }
  ]
}

{
  "results": [
    { "status": 201, "data": { "id": "789", ... } },
    { "status": 200, "data": { "id": "123", ... } },
    { "status": 204 }
  ]
}

GET /api/v3/users/123?fields=id,name,email

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "address": { "street": "123 Main St", "city": "NYC" },
      "preferences": { /* ... */ },
      "metadata": { /* ... */ }
      // ... many more fields
    }
  }
}

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

{
  "error": "Validation failed"
}

{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "email",
      "message": "Email format is invalid",
      "suggestion": "Use format: user@example.com"
    },
    {
      "code": "VALIDATION_ERROR",
      "field": "password",
      "message": "Password too weak",
      "suggestion": "Password must be at least 8 characters with uppercase, lowercase, and numbers"
    }
  ]
}

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642694400
X-RateLimit-Window: 3600
Retry-After: 3600

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jun 2025 00:00:00 GMT
Link: <https://docs.example.com/migration/v2-to-v3>; rel="deprecation"

// Before
const API_BASE = 'https://api.example.com/api';

// After
const API_BASE = 'https://api.example.com/api/v3';

// Before (v2) - API Token
const response = await fetch(`${API_BASE}/users`, {
  headers: {
    'Authorization': `Token ${apiToken}`
  }
});

// After (v3) - JWT Bearer
const tokenResponse = await fetch(`${API_BASE}/auth/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password })
});
const { token } = await tokenResponse.json();

const response = await fetch(`${API_BASE}/users`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

// Before (v2)
const user = await response.json();
console.log(user.name);

// After (v3) - Unwrap data object
const { data } = await response.json();
console.log(data.attributes.name);

// Or use SDK
import { ApiClient } from '@company/api-sdk';
const client = new ApiClient(token);
const user = await client.users.get('123');
console.log(user.name); // SDK handles unwrapping

// Before (v2)
try {
  const response = await fetch(`${API_BASE}/users`);
  if (!response.ok) {
    const error = await response.json();
    console.error(error.error);
  }
} catch (error) {
  console.error(error);
}

// After (v3) - Handle multiple errors
try {
  const response = await fetch(`${API_BASE}/users`);
  if (!response.ok) {
    const { errors } = await response.json();
    errors.forEach(err => {
      console.error(`${err.field}: ${err.message}`);
      console.log(`Suggestion: ${err.suggestion}`);
    });
  }
} catch (error) {
  console.error(error);
}

// Before (v2)
const response = await fetch(`${API_BASE}/users?page=1&per_page=20`);

// After (v3)
const response = await fetch(`${API_BASE}/users?page[number]=1&page[size]=20`);

// Response structure
{
  "data": [...],
  "meta": {
    "page": {
      "current": 1,
      "size": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "links": {
    "first": "/api/v3/users?page[number]=1",
    "last": "/api/v3/users?page[number]=8",
    "next": "/api/v3/users?page[number]=2",
    "prev": null
  }
}

// Run tests against v3 API
npm run test:api -- --api-version=v3

// Test migration gradually
const USE_V3 = process.env.USE_API_V3 === 'true';
const API_BASE = USE_V3
  ? 'https://api.example.com/api/v3'
  : 'https://api.example.com/api/v2';

# JavaScript/TypeScript
npm install @company/api-sdk@^3.0.0

# Python
pip install company-api-sdk>=3.0.0

# Ruby
gem install company-api-sdk -v '~> 3.0'

# Go
go get github.com/company/api-sdk/v3

## Best Practices

### ✅ DO
- Clearly mark breaking changes
- Provide migration guides with code examples
- Include before/after comparisons
- Document deprecation timelines
- Show impact on existing implementations
- Provide SDKs for major versions
- Use semantic versioning
- Give advance notice (3-6 months)
- Maintain backward compatibility when possible
- Document version support policy

### ❌ DON'T
- Make breaking changes without notice
- Remove endpoints without deprecation period
- Skip migration examples
- Forget to version your API
- Change behavior without documentation
- Rush deprecations

## Resources

- [Stripe API Versioning](https://stripe.com/docs/api/versioning)
- [GitHub API Changes](https://docs.github.com/en/rest/overview/api-versions)
- [Semantic Versioning](https://semver.org/)
- [JSON:API Specification](https://jsonapi.org/)