API Sözleşme Testi Nasıl Uygulanır: Güvenilir API'ler için En İyi Uygulamalar

Ön uç uygulamanızın, arka uç API'sinin beklenmedik bir şekilde değişmesi nedeniyle aniden bozulduğu bir durumla hiç karşılaştınız mı? Bu tür kesintiler tüm sisteminize yayılarak kullanıcıların hayal kırıklığına uğramasına ve telaşlı hata ayıklama oturumlarına yol açabilir. İşte tam da bu noktada API Sözleşme Testi devreye girer; API üreticileri ve tüketicileri arasında uyumu sağlayan metodik bir yaklaşımdır. Bu kılavuzda, API Sözleşme Testinin temellerini, zorluklarını ve otomasyon stratejilerini keşfederek inceliklerine derinlemesine ineceğiz. Sonunda, API Sözleşme Testinin sadece iyi bir özellik olmakla kalmayıp sağlam yazılım geliştirmenin temel taşı olduğunu anlayacaksınız. Gelin, API Sözleşme Testini iş akışlarınıza sorunsuz bir şekilde nasıl entegre edeceğimizi keşfetmek için bu yolculuğa birlikte çıkalım.

API Sözleşme Testi Nedir?

API sözleşme testi, bir API sağlayıcısı ile tüketicileri arasındaki üzerinde anlaşmaya varılan arayüzün sistemler geliştikçe tutarlı kalmasını sağlar. OpenAPI veya Swagger spesifikasyonları aracılığıyla tanımlanan bu sözleşme, her iki tarafın da güvendiği resmi bir anlaşma gibi, beklenen istek ve yanıt yapısını (uç noktalar, yöntemler, şemalar, başlıklar ve durum kodları) açıklar.

API sözleşme testi genellikle iki şekilde yapılır. Tüketici Odaklı Sözleşmeler (CDC'ler), mikro hizmetlerde entegrasyon hatalarını önlemek için tüketicinin bakış açısından beklentileri tanımlar. API ekibi tarafından oluşturulan sağlayıcı tanımlı sözleşmeler, daha geniş bir doğrulama için desteklenen tüm etkileşimleri kapsar. Fonksiyonel veya birim testlerinden farklı olarak, bu testler temel mantığa değil, kesinlikle API arayüzüne odaklanır.

API Sözleşme Testinin Önemi

Geliştirme yaşam döngünüzde neden API sözleşme testine öncelik vermelisiniz? Küçük bir API değişikliği, akışın aşağısında büyük hatalara neden olabilir. Sözleşmeleri erken doğrulamak, hizmetler arasında tutarlı iletişimi sağlar ve sorunların üretime ulaşmasından çok önce önlenmesine yardımcı olur.

API sözleşme testinin başlıca faydaları şunlardır:

• Bozulmaya neden olan değişikliklerin erken tespiti
• Dağıtık sistemlerde güvenilirlik
• Güvenli, emin dağıtımlar
• Paralel geliştirme
• Daha güçlü CI/CD iş akışları
• Uzun vadeli sürdürülebilirlik

E-ticaret veya SaaS gibi hızlı tempolu, yinelemeli ortamlarda, API sözleşme testi istikrarlı, öngörülebilir ve kullanıcı dostu uygulamalar sunmak için vazgeçilmez hale gelir.

Manuel API Sözleşme Testinin Zorlukları

API'ler büyüdükçe, API sözleşme testinin manuel olarak yürütülmesi hızla pratik olmaktan çıkar. İstekleri manuel olarak oluşturmak, yanıtları spesifikasyonlara göre kontrol etmek ve başlıkları veya hata kodlarını doğrulamak yavaş, hataya açık ve ölçeklendirilmesi zordur.

Manuel API sözleşme testinin başlıca zorlukları şunlardır:

• Yüksek çaba ve zaman maliyeti
• İnsan hatası
• Düşük ölçeklenebilirlik
• Dağıtık ekiplerde koordinasyon yükü
• Azalan güven

Bu sınırlamalar, hızlı gelişen, güvenilir API geliştirme için otomatik API sözleşme testinin neden gerekli olduğunu vurgulamaktadır. Yavaş, tutarsız manuel kontroller, API istikrarına olan güveni zayıflatır.

Apidog'da API Sözleşme Testine Başlarken

Projelerinizde API Sözleşme Testinden faydalanmaya hazır mısınız? Kapsamlı bir API geliştirme platformu olan Apidog, yerleşik şema doğrulama ve betik yetenekleriyle bunu basitleştirerek ideal bir başlangıç noktası sunar.

Apidog'da API Sözleşme Testini etkinleştirmek için, OpenAPI spesifikasyonunuzu içe aktararak veya yeni bir proje oluşturarak başlayın; Apidog, şemalardan otomatik olarak testler oluşturarak kurulumu kolaylaştırır.

Uygulamalı bir örnek için, API keşfi için klasik bir örnek olan Apidog'un demo Pet Store projesini kullanalım. Apidog'u başlatın, "Demo Pet" projesini seçin ve "/pet/{petId}" GET uç noktasına gidin (not: sorgu "/get/pets/{id}" kullanır, ancak standart Petstore ile uyumlu olarak bu "/pet/{petId}"dir). Sol üstteki açılır menüden ortamı "petstore env" veya "localmock" olarak ayarlayın,

ardından isteği yürütün. Aşağıdaki gibi bir yanıt almalısınız:

{
  "id": 1,
  "category": {
    "id": 1,
    "name": "dogs"
  },
  "name": "doggie",
  "photoUrls": [],
  "tags": [],
  "status": "available"
}

Bu, sözleşme doğrulaması için zemin hazırlar.

"Test Senaryoları" sekmesine gidin ve "Vaka Ekle"ye tıklayarak yeni bir süit oluşturun.

Ön işlemciler bölümünde, JSON şemanızı ve değişkenlerinizi tanımlamak için özel bir betik ekleyin:

Adım 1: Ön İşlemcilere Gidin

Adım 2: Özel JS kodunu ekleyin

// Set petId if not set (as string)
if (!pm.environment.get("petId")) {
  pm.environment.set("petId", "1");
}

// Define JSON schema for the pet response
const petSchema = {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "category": {
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"],
      "additionalProperties": true
    },
    "name": { "type": "string" },
    "photoUrls": {
      "type": "array",
      "items": { "type": "string", "format": "uri" },
      "minItems": 0
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" }
        },
        "required": ["id", "name"],
        "additionalProperties": true
      },
      "minItems": 0
    },
    "status": {
      "type": "string",
      "enum": ["available", "pending", "sold"]
    }
  },
  "required": ["id", "name", "photoUrls", "status"],
  "additionalProperties": true
};

// Store the schema in an environment variable (stringify it)
pm.environment.set("pet_schema", JSON.stringify(petSchema));

// (Optional) log to console for debugging
console.log("Pre-processor: petId =", pm.environment.get("petId"));

Ardından, son işlemcilerde doğrulama betiğini yapıştırın:

// Use AJV for schema validation
var Ajv = require('ajv');
var ajv = new Ajv({ allErrors: true, logger: console });

// Retrieve schema from environment
var raw = pm.environment.get("pet_schema");
var schema;
try {
  schema = (typeof raw === 'string') ? JSON.parse(raw) : raw;
} catch (err) {
  pm.test('Schema is valid JSON', function() {
    pm.expect(false, 'pet_schema is not valid JSON: ' + err.message).to.be.true;
  });
  // Stop further tests
  return;
}

// Parse the response body as JSON
var responseData;
try {
  responseData = pm.response.json();
} catch (err) {
  pm.test('Response is valid JSON', function() {
    pm.expect(false, 'Response body is not JSON: ' + err.message).to.be.true;
  });
  return;
}

// Test status code
pm.test('Status code is 200', function() {
  pm.expect(pm.response.status).to.eql("OK");
});

// Validate schema
pm.test('Response matches pet schema', function() {
  var valid = ajv.validate(schema, responseData);
  if (!valid) {
    console.log('AJV Errors:', ajv.errors);
  }
  pm.expect(valid, 'Response does not match schema, see console for errors').to.be.true;
});

// Additional assertions
pm.test('Returned id matches requested petId', function() {
  var requested = pm.environment.get("petId");
  // petId is stored as string, but id in response is integer
  var requestedNum = Number(requested);
  if (!isNaN(requestedNum)) {
    pm.expect(responseData.id).to.eql(requestedNum);
  } else {
    pm.expect(String(responseData.id)).to.eql(String(requested));
  }
});

pm.test('Name is a string', function() {
  pm.expect(responseData.name).to.be.a('string');
});

pm.test('Status is one of expected values', function() {
  pm.expect(responseData.status).to.be.oneOf(['available', 'pending', 'sold']);
});

// Optional: more detailed checks (category, photoUrls, tags)
pm.test('Category has id and name', function() {
  pm.expect(responseData.category).to.have.property('id');
  pm.expect(responseData.category).to.have.property('name');
});

pm.test('At least one photo URL', function() {
  pm.expect(responseData.photoUrls).to.be.an('array').that.is.not.empty;
});

pm.test('Tags are valid objects', function() {
  pm.expect(responseData.tags).to.be.an('array');
  if (responseData.tags.length > 0) {
    responseData.tags.forEach(function(tag) {
      pm.expect(tag).to.have.property('id');
      pm.expect(tag).to.have.property('name');
    });
  }
});

"Çalıştır"a basarak yürütün. Apidog, sonuçları sağda gösterir: "Başarılı" veya "Başarısız", genişletilebilir ayrıntılarla. Başarılı bir çalıştırma şunu gösterebilir:

API Yanıtı:

{
  "id": 1,
  "category": {
    "id": 1,
    "name": "dog"
  },
  "name": "Jasper",
  "photoUrls": [
    "https://loremflickr.com/400/400?lock=7187959506185006"
  ],
  "tags": [
    {
      "id": 3,
      "name": "Yellow"
    }
  ],
  "status": "available"
}

Geçen Testler:

1. Durum kodu 200
2. Yanıt pet şemasıyla eşleşiyor
3. Dönen kimlik istenen petId ile eşleşiyor
4. Ad bir dizgedir
5. Durum beklenen değerlerden biridir
6. Kategorinin kimliği ve adı var
7. En az bir fotoğraf URL'si
8. Etiketler geçerli nesnelerdir

Hatayı simüle etmek için, durum kodu testini "OK" yerine bir sayı (200) beklemesi için değiştirin,

ardından tekrar çalıştırın ve onaylama hatasını gözlemleyin.

Regresyon çalıştırmaları için süiti kaydedin. Apidog'un, şema kontrolleri için AJV entegrasyonu ile sezgisel arayüzü, API Sözleşme Testini demokratikleştirerek karmaşık doğrulamaları rutin görevlere dönüştürür.

Sıkça Sorulan Sorular

S1. API Sözleşme Testini entegrasyon testinden ayıran nedir?

Cevap: API Sözleşme Testi, iş mantığını yürütmeden arayüz sözleşmesini doğrular; entegrasyon testi ise hizmetlerin veri akışı ve bağımlılıklar dahil olmak üzere nasıl etkileşim kurduğunu inceler.

S2. API Sözleşme Testi GraphQL API'lerine uygulanabilir mi?

Cevap: Evet, öncelikli olarak REST için tasarlanmış olsa da, Pact gibi araçlar GraphQL şemalarını destekleyerek sorgu/yanıt yapılarına ve mutasyonlara odaklanır.

S3. API Sözleşme Testi bir CI/CD hattında ne sıklıkla çalıştırılmalıdır?

Cevap: İdeal olarak, sorunları erken yakalamak için her commit veya pull request'te ve kapsamlı kapsama için gece çalıştırmalarıyla.

S4. Ekibimde sözleşme testi için bir OpenAPI spesifikasyonu yoksa ne yapmalıyım?

Cevap: Swagger Codegen gibi araçlar kullanarak mevcut koddan bir tane oluşturarak başlayın, ardından temel oluşturmak için işbirliği içinde geliştirin.

S5. API Sözleşme Testi eski API'ler için uygun mudur?

Cevap: Kesinlikle—mevcut davranışı belgelemek için spesifikasyonları uyarlayın, ardından modernizasyon sırasında regresyonlara karşı koruma sağlamak için testleri otomatikleştirin.

Sonuç

Keşfimizi tamamlarken, API Sözleşme Testinin birbirine bağlı bir dünyada güvenilir, ölçeklenebilir API'ler için kilit nokta olduğu ortaya çıkıyor. Manuel angaryayı azaltmaktan otomatik korumaları güçlendirmeye kadar, ekipleri korkusuzca yenilik yapmaya donatır. Uygulamalarınızın esneklik ve verimlilik kazanmasını izlerken, pratiğinizi yükseltmek için Apidog gibi araçları benimseyin. Mevcut sözleşmeleri iyileştirmek veya yenilerini oluşturmak olsun, üstün API yönetimine giden yol tek, iyi tanımlanmış bir testle başlar.