Cara Menerapkan API Contract Testing: Praktik Terbaik untuk API yang Andal

Pernahkah Anda mengalami situasi di mana aplikasi frontend Anda tiba-tiba rusak karena API backend berubah secara tak terduga? Gangguan semacam itu dapat menyebar ke seluruh sistem Anda, menyebabkan pengguna frustrasi dan sesi debugging yang panik. Di sinilah Uji Kontrak API berperan—pendekatan metodis yang memastikan keselarasan antara produsen dan konsumen API. Dalam panduan ini, kita akan mempelajari seluk-beluk Uji Kontrak API, menjelajahi dasar-dasarnya, tantangan, dan strategi otomatisasi. Pada akhirnya, Anda akan memahami mengapa Uji Kontrak API bukan hanya hal yang menyenangkan untuk dimiliki, tetapi juga landasan pengembangan perangkat lunak yang kuat. Mari kita memulai perjalanan ini bersama-sama, mengungkap cara menyatukan Uji Kontrak API secara mulus ke dalam alur kerja Anda.

💡

Ingin alat Pengujian API yang hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform terintegrasi, All-in-One untuk Tim Developer Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!

button

Apa itu Uji Kontrak API?

Uji kontrak API memastikan bahwa antarmuka yang disepakati antara penyedia API dan konsumennya tetap konsisten seiring berkembangnya sistem. Didefinisikan melalui spesifikasi OpenAPI atau Swagger, kontrak ini menjelaskan struktur permintaan dan respons yang diharapkan—titik akhir, metode, skema, header, dan kode status—mirip seperti perjanjian formal yang diandalkan kedua belah pihak.

Uji kontrak API umumnya berbentuk dua macam. Kontrak Berbasis Konsumen (Consumer-Driven Contracts/CDC) mendefinisikan ekspektasi dari sudut pandang konsumen untuk mencegah kegagalan integrasi dalam microservice. Kontrak yang didefinisikan penyedia, yang dibuat oleh tim API, mencakup semua interaksi yang didukung untuk validasi yang lebih luas. Tidak seperti pengujian fungsional atau unit, pengujian ini berfokus secara ketat pada antarmuka API, bukan pada logika dasarnya.

Pentingnya Uji Kontrak API

Mengapa memprioritaskan pengujian kontrak API dalam siklus pengembangan Anda? Perubahan API kecil dapat menyebabkan kegagalan besar di hilir. Memvalidasi kontrak sejak awal memastikan komunikasi yang konsisten antar layanan dan mencegah masalah jauh sebelum mencapai produksi.

Manfaat utama pengujian kontrak API meliputi:

Deteksi dini perubahan yang merusak
Keandalan dalam sistem terdistribusi
Penyebaran yang aman dan percaya diri
Pengembangan paralel
Alur kerja CI/CD yang lebih kuat
Pemeliharaan jangka panjang

Dalam lingkungan yang serba cepat dan iteratif seperti e-commerce atau SaaS, pengujian kontrak API menjadi penting untuk menghasilkan aplikasi yang stabil, dapat diprediksi, dan ramah pengguna.

Tantangan Uji Kontrak API Manual

Pelaksanaan manual pengujian kontrak API dengan cepat menjadi tidak praktis seiring dengan pertumbuhan API. Membuat permintaan secara manual, memeriksa respons terhadap spesifikasi, dan memvalidasi header atau kode kesalahan lambat, rawan kesalahan, dan sulit diskalakan.

Tantangan utama pengujian kontrak API manual meliputi:

Biaya tenaga dan waktu yang tinggi
Kesalahan manusia
Skalabilitas yang buruk
Overhead koordinasi dalam tim terdistribusi
Kepercayaan yang berkurang

Keterbatasan ini menyoroti mengapa **pengujian kontrak API** otomatis sangat penting untuk pengembangan API yang cepat dan andal. Pemeriksaan manual yang lambat dan tidak konsisten merusak kepercayaan terhadap stabilitas API.

Memulai Uji Kontrak API di Apidog

Siap memanfaatkan Pengujian Kontrak API dalam proyek Anda? Apidog, platform pengembangan API yang komprehensif, menyederhanakannya dengan validasi skema bawaan dan kemampuan scripting, menjadikannya titik masuk yang ideal.

Untuk mengaktifkan Uji Kontrak API di Apidog, mulailah dengan mengimpor spesifikasi OpenAPI Anda atau membuat proyek baru—Apidog secara otomatis menghasilkan pengujian dari skema, menyederhanakan pengaturan.

Untuk contoh langsung, mari kita gunakan proyek Demo Pet Store Apidog, sebuah klasik untuk eksplorasi API. Luncurkan Apidog, pilih proyek "Demo Pet", dan navigasikan ke titik akhir GET "/pet/{petId}" (catatan: kueri menggunakan "/get/pets/{id}", tetapi sesuai dengan Petstore standar, itu adalah "/pet/{petId}"). Atur lingkungan ke "petstore env" atau "localmock" melalui menu drop-down kiri atas,

lalu jalankan permintaan tersebut. Anda akan menerima respons seperti:

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

Ini menyiapkan panggung untuk validasi kontrak.

Buka tab "Test Cases" dan buat suite baru dengan mengeklik "Add Case."

Di bagian pre-processor, tambahkan skrip kustom untuk mendefinisikan skema JSON dan variabel Anda:

Langkah 1: Buka Pre-Processor

Langkah 2: Tambahkan kode Custom JS

menambahkan kode skrip uji js kustom di Apidog

// Set petId jika belum diatur (sebagai string)
if (!pm.environment.get("petId")) {
  pm.environment.set("petId", "1");
}

// Definisikan skema JSON untuk respons hewan peliharaan
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
};

// Simpan skema dalam variabel lingkungan (stringifikasikan)
pm.environment.set("pet_schema", JSON.stringify(petSchema));

// (Opsional) log ke konsol untuk debugging
console.log("Pre-processor: petId =", pm.environment.get("petId"));

Selanjutnya, di post-processor, tempelkan skrip validasi:

// Gunakan AJV untuk validasi skema
var Ajv = require('ajv');
var ajv = new Ajv({ allErrors: true, logger: console });

// Ambil skema dari lingkungan
var raw = pm.environment.get("pet_schema");
var schema;
try {
  schema = (typeof raw === 'string') ? JSON.parse(raw) : raw;
} catch (err) {
  pm.test('Schema adalah JSON yang valid', function() {
    pm.expect(false, 'pet_schema bukan JSON yang valid: ' + err.message).to.be.true;
  });
  // Hentikan pengujian selanjutnya
  return;
}

// Parsing isi respons sebagai JSON
var responseData;
try {
  responseData = pm.response.json();
} catch (err) {
  pm.test('Respons adalah JSON yang valid', function() {
    pm.expect(false, 'Isi respons bukan JSON: ' + err.message).to.be.true;
  });
  return;
}

// Uji kode status
pm.test('Kode status adalah 200', function() {
  pm.expect(pm.response.status).to.eql("OK");
});

// Validasi skema
pm.test('Respons cocok dengan skema hewan peliharaan', function() {
  var valid = ajv.validate(schema, responseData);
  if (!valid) {
    console.log('AJV Errors:', ajv.errors);
  }
  pm.expect(valid, 'Respons tidak cocok dengan skema, lihat konsol untuk kesalahan').to.be.true;
});

// Pernyataan tambahan
pm.test('Id yang dikembalikan cocok dengan petId yang diminta', function() {
  var requested = pm.environment.get("petId");
  // petId disimpan sebagai string, tetapi id dalam respons adalah 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('Nama adalah string', function() {
  pm.expect(responseData.name).to.be.a('string');
});

pm.test('Status adalah salah satu nilai yang diharapkan', function() {
  pm.expect(responseData.status).to.be.oneOf(['available', 'pending', 'sold']);
});

// Opsional: pemeriksaan lebih detail (kategori, photoUrls, tags)
pm.test('Kategori memiliki id dan nama', function() {
  pm.expect(responseData.category).to.have.property('id');
  pm.expect(responseData.category).to.have.property('name');
});

pm.test('Setidaknya satu URL foto', function() {
  pm.expect(responseData.photoUrls).to.be.an('array').that.is.not.empty;
});

pm.test('Tag adalah objek yang valid', 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');
    });
  }
});

Tekan "Run" untuk mengeksekusi. Apidog menampilkan hasil di sebelah kanan: "Passed" atau "Failed", dengan detail yang dapat diperluas. Hasil yang berhasil mungkin menunjukkan:

Respons API:

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

Pengujian Lulus:

Kode status adalah 200
Respons cocok dengan skema hewan peliharaan
ID yang dikembalikan cocok dengan ID hewan peliharaan yang diminta
Nama adalah string
Status adalah salah satu nilai yang diharapkan
Kategori memiliki ID dan nama
Setidaknya satu URL foto
Tag adalah objek yang valid

Untuk mensimulasikan kegagalan, ubah pengujian kode status untuk mengharapkan angka (200) alih-alih "OK",

lalu jalankan kembali dan amati kesalahan pernyataan.

Simpan suite untuk uji regresi. Antarmuka Apidog yang intuitif, dengan integrasi AJV untuk pemeriksaan skema, mendemokratisasikan Uji Kontrak API, mengubah validasi kompleks menjadi tugas rutin.

Pertanyaan yang Sering Diajukan

Q1. Apa yang membedakan Uji Kontrak API dari pengujian integrasi?

Jawab: Uji Kontrak API memvalidasi kontrak antarmuka tanpa mengeksekusi logika bisnis, sedangkan pengujian integrasi memeriksa bagaimana layanan berinteraksi, termasuk aliran data dan dependensi.

Q2. Bisakah Uji Kontrak API diterapkan pada API GraphQL?

Jawab: Ya, meskipun terutama dirancang untuk REST, alat seperti Pact mendukung skema GraphQL, berfokus pada struktur kueri/respons dan mutasi.

Q3. Seberapa sering Uji Kontrak API harus dijalankan dalam pipeline CI/CD?

Jawab: Idealnya, pada setiap commit atau pull request untuk mendeteksi masalah sejak dini, dengan eksekusi setiap malam untuk cakupan yang komprehensif.

Q4. Bagaimana jika tim saya tidak memiliki spesifikasi OpenAPI untuk pengujian kontrak?

Jawab: Mulailah dengan membuat satu dari kode yang ada menggunakan alat seperti Swagger Codegen, lalu sempurnakan secara kolaboratif untuk menetapkan baseline.

Q5. Apakah Uji Kontrak API cocok untuk API lama?

Jawab: Tentu saja—sesuaikan spesifikasi untuk mendokumentasikan perilaku saat ini, lalu otomatisasi pengujian untuk melindungi dari regresi selama modernisasi.

Kesimpulan

Saat kita mengakhiri eksplorasi kita, menjadi jelas bahwa Uji Kontrak API adalah inti untuk API yang andal dan terukur di dunia yang saling terhubung. Dari mitigasi kerja keras manual hingga pemberdayaan perlindungan otomatis, Uji Kontrak API membekali tim untuk berinovasi tanpa rasa takut. Manfaatkan alat seperti Apidog untuk meningkatkan praktik Anda, dan saksikan bagaimana aplikasi Anda memperoleh ketahanan dan efisiensi. Baik menyempurnakan kontrak yang ada atau membentuk yang baru, jalur menuju tata kelola API yang unggul dimulai dengan satu pengujian yang terdefinisi dengan baik.

💡

button