AWS CDK ile API Versiyonlama: Bir Üretim Vaka Çalışması

// lib/config/api-versions.tsexport interface ApiVersion {  version: string;  status: 'alpha' | 'beta' | 'stable' | 'deprecated' | 'sunset';  launchedAt: Date;  deprecatedAt?: Date;  sunsetAt?: Date;  monthlyActiveClients?: number;  // Bunu takip edin!  breakingChanges: string[];  supportedFeatures: Set<string>;}
export const API_VERSIONS: Record<string, ApiVersion> = {  v1: {    version: 'v1',    status: 'deprecated',    launchedAt: new Date('2022-01-15'),    deprecatedAt: new Date('2024-01-15'),    sunsetAt: new Date('2025-01-15'),    monthlyActiveClients: 28,  // Legacy devlet müşterileri    breakingChanges: [],    supportedFeatures: new Set(['basic-crud']),  },  v2: {    version: 'v2',    status: 'stable',    launchedAt: new Date('2023-06-01'),    monthlyActiveClients: 156,    breakingChanges: [      'Tüm yanıtlarda userId yerine user_id kullanıldı',      'XML desteği kaldırıldı',      'Email alanı zorunlu hale getirildi',    ],    supportedFeatures: new Set(['basic-crud', 'pagination', 'filtering']),  },  v3: {    version: 'v3',    status: 'beta',    launchedAt: new Date('2024-03-01'),    monthlyActiveClients: 42,    breakingChanges: [      'JSON:API spec\'e geçildi',      'Tüm ID\'ler UUID\'ye değiştirildi',      'Kaynaklar data özelliği altında yuvalandı',    ],    supportedFeatures: new Set([      'basic-crud',      'pagination',      'filtering',      'webhooks',      'graphql',      'batch-operations'    ]),  },};

// lib/stacks/versioned-api-stack.tsimport { RestApi, MethodLoggingLevel, LambdaIntegration } from 'aws-cdk-lib/aws-apigateway';import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';import { Duration, Stack, StackProps } from 'aws-cdk-lib';import { Alarm, Metric } from 'aws-cdk-lib/aws-cloudwatch';import { Construct } from 'constructs';
export class VersionedApiStack extends Stack {  constructor(scope: Construct, id: string, props: StackProps) {    super(scope, id, props);
    const api = new RestApi(this, 'MultiVersionAPI', {      restApiName: 'production-api',      // Bunu zor yoldan öğrendim: CloudWatch'u her zaman etkinleştirin      deployOptions: {        loggingLevel: MethodLoggingLevel.INFO,        dataTraceEnabled: true,  // userId olayı sırasında beni kurtardı        metricsEnabled: true,        tracingEnabled: true,      },    });
    // Versiyon kontrol Lambda'sını ekle - bu kritik    const versionCheckFn = new NodejsFunction(this, 'VersionCheck', {      entry: 'src/middleware/version-check.ts',      memorySize: 256,  // Fazla gerek yok      timeout: Duration.seconds(3),      environment: {        VERSIONS: JSON.stringify(API_VERSIONS),        SLACK_WEBHOOK: process.env.SLACK_WEBHOOK!,  // Kullanımdan kaldırılan versiyon kullanımında uyar      },    });
    // Her versiyonu ayarla    Object.entries(API_VERSIONS).forEach(([version, config]) => {      if (config.status === 'sunset') return;  // Sunset versiyonlarını dağıtma
      const versionResource = api.root.addResource(version);      this.setupVersionEndpoints(versionResource, config);    });
    // Kritik: versiyon keşif endpoint'i    this.addVersionDiscovery(api);
    // v1 sunset sırasında bizi kurtaran alarm    new Alarm(this, 'DeprecatedVersionHighUsage', {      metric: new Metric({        namespace: 'API/Versions',        metricName: 'DeprecatedVersionCalls',        statistic: 'Sum',      }),      threshold: 1000,      evaluationPeriods: 1,    });  }
  private setupVersionEndpoints(resource: IResource, config: ApiVersion) {    // Gerçek konuşalım: versiyonlar arasında 47 Lambda fonksiyonumuz var    // Zarif değil, ama yönetilebilir
    const handlers = new Map<string, Function>();
    // Kullanıcı endpoint'leri - çoğu kırıcı değişikliğin kaynağı    const usersResource = resource.addResource('users');
    const listUsersHandler = new NodejsFunction(this, `ListUsers-${config.version}`, {      entry: `src/handlers/${config.version}/users/list.ts`,      memorySize: config.version === 'v1' ? 512 : 1024,  // V1 verimsiz      timeout: Duration.seconds(29),  // API Gateway maximum timeout (REST API'ler için 29 saniyeye kadar)      environment: {        TABLE_NAME: process.env.USERS_TABLE!,        VERSION: config.version,        FEATURES: [...config.supportedFeatures].join(','),        // Bu sayısız kez hata ayıklama zamanı kazandırdı        DEPLOYMENT_TIME: new Date().toISOString(),      },      bundling: {        // Versiyona özel bağımlılıklar        externalModules: [          '@aws-sdk/client-dynamodb',  // AWS SDK v3 for Node.js 18+ runtime          '@aws-sdk/client-cloudwatch',          ...(config.version === 'v1' ? ['xmlbuilder'] : []),  // V1 XML desteği        ],      },    });
    usersResource.addMethod('GET', new LambdaIntegration(listUsersHandler), {      requestParameters: {        'method.request.querystring.page': config.supportedFeatures.has('pagination'),        'method.request.querystring.limit': config.supportedFeatures.has('pagination'),        'method.request.querystring.filter': config.supportedFeatures.has('filtering'),        // V3 özel parametreler        'method.request.querystring.include': config.version === 'v3',        'method.request.querystring.fields': config.version === 'v3',      },    });
    // Her versiyon çağrısını takip et - bu metrik altın değerinde    listUsersHandler.metricInvocations().createAlarm(this, `HighTraffic-${config.version}`, {      threshold: 10000,      evaluationPeriods: 1,      alarmDescription: `${config.version} üzerinde yüksek trafik - ölçeklendirmeyi kontrol et`,    });  }}

// src/handlers/v1/users/list.ts// Bu kod 3 yaşında ve belli oluyorexport const handler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {  console.log('V1 handler çağrıldı', {    path: event.path,    clientIp: event.requestContext.identity.sourceIp,    userAgent: event.headers['User-Agent'],  });
  try {    // V1 sayfalamayı desteklemiyor, her şeyi döndürüyor    // Evet, bu korkunç. Hayır, düzeltemeyiz.    const users = await getAllUsers();  // Bu bir keresinde 50K kayıt döndürdü
    // Olaya neden olan alan    const transformedUsers = users.map(u => ({      userId: u.user_id,  // V1 camelCase kullanıyor      userName: u.name,      userEmail: u.email,      createdDate: u.created_at,  // Farklı alan adı çünkü nedenler    }));
    return {      statusCode: 200,      headers: {        'Content-Type': 'application/json',        'X-API-Version': 'v1',        'X-API-Deprecated': 'true',        'X-API-Sunset': '2025-01-15',        'Warning': '299 - "API v1 kullanımdan kaldırıldı. Lütfen v2\'ye geçin. Kılavuzlar: https://docs.api.com/migration"',        // Bir bankacılık müşterisi için eklemek zorunda kaldım        'X-Total-Count': transformedUsers.length.toString(),      },      body: JSON.stringify(transformedUsers),    };  } catch (error) {    // 6 saat prod'da hata ayıkladıktan sonra her şeyi loglamamayı öğrendim    console.error('V1 handler hatası', {      error,      stack: error.stack,      event: JSON.stringify(event),    });
    return {      statusCode: 500,      body: JSON.stringify({        error: 'Internal Server Error',        // V1 müşterileri tam olarak bu formatı bekliyor        errorCode: 'INTERNAL_ERROR',        timestamp: new Date().toISOString(),      }),    };  }};
// src/handlers/v2/users/list.tsexport const handler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {  // V2 50K olayından sonra uygun sayfalama ekledi  const page = parseInt(event.queryStringParameters?.page || '1');  const limit = Math.min(    parseInt(event.queryStringParameters?.limit || '20'),    100  // Birisi limit=10000 istedikten sonra sabit limit  );
  const metrics = {    version: 'v2',    page,    limit,    clientIp: event.requestContext.identity.sourceIp,  };
  // Kullanımdan kaldırılan versiyon kullanımını takip et  if (event.headers['User-Agent']?.includes('OldSDK/1.')) {    await cloudwatch.putMetricData({      Namespace: 'API/Clients',      MetricData: [{        MetricName: 'OutdatedSDKUsage',        Value: 1,        Dimensions: [{ Name: 'Version', Value: 'v2' }],      }],    }).promise();  }
  try {    const { users, total } = await getUsersPaginated({ page, limit });
    // V2 yanıt formatı - beni rahatsız eden tutarsızlığa dikkat edin    const response = {      data: users.map(u => ({        id: u.user_id,  // userId'den değişti        name: u.name,        email: u.email,        status: u.status || 'active',  // Yeni zorunlu alan        created_at: u.created_at,  // Her yerde snake case        updated_at: u.updated_at,      })),      pagination: {        page,        limit,        total,        total_pages: Math.ceil(total / limit),        has_next: page < Math.ceil(total / limit),        has_prev: page > 1,      },      // Müşteriler sayfalamayı anlayamadıktan sonra eklendi      _links: {        self: `/v2/users?page=${page}&limit=${limit}`,        next: page < Math.ceil(total / limit) ? `/v2/users?page=${page + 1}&limit=${limit}` : null,        prev: page > 1 ? `/v2/users?page=${page - 1}&limit=${limit}` : null,      },    };
    return {      statusCode: 200,      headers: {        'Content-Type': 'application/json',        'X-API-Version': 'v2',        'X-RateLimit-Limit': '500',        'X-RateLimit-Remaining': await getRateLimitRemaining(event),        'Cache-Control': 'private, max-age=60',  // Yanlışlıkla önbellekleme olayından sonra eklendi      },      body: JSON.stringify(response),    };  } catch (error) {    logger.error('V2 handler hatası', { error, metrics });    throw error;  // API Gateway halletsin  }};
// src/handlers/v3/users/list.ts// V3: Sonunda doğru yaptığımız yer (çoğunlukla)export const handler = middy(async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {  // V3 JSON:API spec kullanıyor çünkü kurumsal müşteriler talep etti  const params = parseJsonApiParams(event.queryStringParameters);
  // Kademeli dağıtım için özellik bayrakları  const features = await getFeatureFlags('v3', event.headers['X-Client-Id']);
  const { users, total, included } = await getUsersWithRelationships({    ...params,    includeRelationships: params.include,    sparseFields: params.fields,    experimentalFeatures: features,  });
  // JSON:API formatı - sevin ya da nefret edin  const response = {    data: users.map(u => ({      type: 'users',      id: u.id,  // Sonunda her yerde UUID kullanıyoruz      attributes: {        name: u.name,        email: u.email,        status: u.status,        created_at: u.created_at,        updated_at: u.updated_at,      },      relationships: {        organization: {          data: { type: 'organizations', id: u.organization_id },        },        roles: {          data: u.role_ids.map(id => ({ type: 'roles', id })),        },      },      links: {        self: `/v3/users/${u.id}`,      },    })),    included: included,  // İlgili kaynaklar    meta: {      pagination: {        page: params.page.number,        pages: Math.ceil(total / params.page.size),        count: users.length,        total: total,      },      api_version: 'v3',      generated_at: new Date().toISOString(),      experimental_features: [...features],    },    links: generateJsonApiLinks(params, total),  };
  return {    statusCode: 200,    headers: {      'Content-Type': 'application/vnd.api+json',  // JSON:API gereksinimi      'X-API-Version': 'v3',      'X-RateLimit-Limit': '1000',      'X-RateLimit-Remaining': await getRateLimitRemaining(event),      'Vary': 'Accept, X-Client-Id',  // Önbellekleme için önemli    },    body: JSON.stringify(response),  };})  .use(jsonBodyParser())  .use(httpErrorHandler())  .use(correlationIds())  .use(logTimeout())  .use(warmup());

// migrations/v1-to-v2-user-ids.tsexport const migrateUserIds = async () => {  const BATCH_SIZE = 100;  let lastEvaluatedKey: any = undefined;  let migrated = 0;  let failed = 0;
  // İlk geçiş: Yeni alan ekle  do {    const { Items, LastEvaluatedKey } = await dynamodb.scan({      TableName: process.env.USERS_TABLE!,      Limit: BATCH_SIZE,      ExclusiveStartKey: lastEvaluatedKey,    }).promise();
    const batch = Items?.map(item => ({      PutRequest: {        Item: {          ...item,          user_id: item.userId || generateUUID(),  // Yeni alan          _migration: 'v1-to-v2-phase1',          _migrated_at: new Date().toISOString(),        },      },    })) || [];
    if (batch.length > 0) {      try {        await dynamodb.batchWrite({          RequestItems: { [process.env.USERS_TABLE!]: batch },        }).promise();        migrated += batch.length;      } catch (error) {        // Logla ama durma - başarısız öğeleri yeniden deneyeceğiz        console.error('Batch başarısız', { error, batch: batch.map(b => b.PutRequest.Item.userId) });        failed += batch.length;      }    }
    lastEvaluatedKey = LastEvaluatedKey;
    // Sıcak partition'lardan kaçınmak için throttle    await new Promise(resolve => setTimeout(resolve, 100));
  } while (lastEvaluatedKey);
  console.log(`Migrasyon tamamlandı: ${migrated} başarılı, ${failed} başarısız`);
  // İkinci geçiş: Eski alanı kaldır (tüm müşteriler güncellendikten sonra)  // Bunun için 6 ay bekledik};

// sdk/src/client.tsexport class ApiClient {  private version: string;  private warned = new Set<string>();
  constructor(options: ClientOptions = {}) {    this.version = options.version || 'v2';  // Varsayılan olarak stable
    if (this.version === 'v1' && !this.warned.has('deprecation')) {      console.warn(        '\x1b[33m%s\x1b[0m',  // Sarı metin        '[KULLANIMDAN KALDIRILMA] API v1 2025-01-15 tarihinde kaldırılacak. ' +        'Migrasyon kılavuzu: https://docs.api.com/migration'      );      this.warned.add('deprecation');
      // SDK versiyon kullanımını takip et      this.trackEvent('sdk_deprecation_warning', { version: 'v1' });    }  }
  async getUsers(options?: GetUsersOptions) {    const url = this.buildUrl('users', options);    const response = await this.request(url);
    // Versiyonlar arasında yanıtları normalize et    return this.normalizeUserResponse(response);  }
  private normalizeUserResponse(response: any): User[] {    switch (this.version) {      case 'v1':        // V1 düz dizi döndürür        return response.map((u: any) => ({          id: u.userId,          name: u.userName,          email: u.userEmail,          createdAt: new Date(u.createdDate),          // V1'de bunlar yok          status: 'active',          updatedAt: new Date(u.createdDate),        }));
      case 'v2':        // V2 sayfalı yanıt döndürür        return response.data.map((u: any) => ({          id: u.id,          name: u.name,          email: u.email,          status: u.status,          createdAt: new Date(u.created_at),          updatedAt: new Date(u.updated_at),        }));
      case 'v3':        // V3 JSON:API formatı döndürür        return response.data.map((u: any) => ({          id: u.id,          name: u.attributes.name,          email: u.attributes.email,          status: u.attributes.status,          createdAt: new Date(u.attributes.created_at),          updatedAt: new Date(u.attributes.updated_at),          // V3 ilişkileri içerir          organizationId: u.relationships?.organization?.data?.id,          roleIds: u.relationships?.roles?.data?.map((r: any) => r.id) || [],        }));
      default:        throw new Error(`Bilinmeyen API versiyonu: ${this.version}`);    }  }}

// lib/constructs/api-monitoring.tsexport class ApiMonitoring extends Construct {  constructor(scope: Construct, id: string) {    super(scope, id);
    // Gerçekten bakılan dashboard    const dashboard = new Dashboard(this, 'ApiDashboard', {      dashboardName: 'api-versions-prod',      defaultInterval: Duration.hours(3),  // Faydalı olacak kadar yakın    });
    // Versiyon dağılımı - v2 dağıtımı sırasında şahin gibi izledim    dashboard.addWidgets(      new GraphWidget({        title: 'API Versiyon Dağılımı (isteklerin %\'si)',        left: [v1Percentage, v2Percentage, v3Percentage],        leftYAxis: { max: 100, min: 0 },        period: Duration.minutes(5),        statistic: 'Average',        // Bu açıklama bizi v1'i çok erken kullanımdan kaldırmaktan kurtardı        leftAnnotations: [{          label: 'Min güvenli eşik',          value: 5,          color: Color.RED,        }],      })    );
    // Önemli olan metrik: versiyona göre müşteri hataları    dashboard.addWidgets(      new GraphWidget({        title: 'Versiyona Göre 4xx Hataları',        left: [          new MathExpression({            expression: 'RATE(m1)',            usingMetrics: {              m1: v1Errors,            },            label: 'V1 Hata Oranı',            color: Color.RED,          }),          // v2, v3 için benzer        ],      })    );
    // Kullanımdan kaldırma uyarısı etkinliği    const deprecationAlarm = new Alarm(this, 'V1StillHighUsage', {      metric: v1Percentage,      threshold: 10,      evaluationPeriods: 3,      comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,      alarmDescription: 'V1 hala 10%\'un üzerinde - sunset ertelenmeli mi?',      treatMissingData: TreatMissingData.NOT_BREACHING,    });
    deprecationAlarm.addAlarmAction(      new SnsAction(Topic.fromTopicArn(this, 'AlertTopic', process.env.ALERT_TOPIC_ARN!))    );  }}

// Bu endpoint diğer tüm endpoint'lerden daha fazla destek bileti kaydediyorapp.get('/api', (req, res) => {  res.json({    versions: {      v1: {        status: 'deprecated',        sunset_date: '2025-01-15',        docs: 'https://docs.api.com/v1',        migration_guide: 'https://docs.api.com/v1-to-v2',      },      v2: {        status: 'stable',        docs: 'https://docs.api.com/v2',      },      v3: {        status: 'beta',        docs: 'https://docs.api.com/v3',        breaking_changes: 'https://docs.api.com/v3-breaking-changes',      },    },    current_stable: 'v2',    recommended: 'v2',    your_version: detectVersion(req),  // Müşterinin kullandığı  });});