Beklediğiniz yanıtı sola, gerçekte aldığınız yanıtı sağa yapıştırın ve değişen her alanı görün. Backend, QA ve entegrasyon işleri için tasarlandı. Hiçbir şey tarayıcınızdan dışarı çıkmaz.
İki HTTP API yanıt body'sini karşılaştırmak için ücretsiz, tarayıcı içi bir araç. Solda staging'den aldığınız JSON, sağda production'dan aldığınız JSON yapıştırın; farklılıklar karakter karakter vurgulanır. Metin makinenizden ayrılmaz; bu önemlidir, çünkü gerçek API yanıtları sıklıkla müşteri e-posta adresleri, oturum token'ları, dahili kullanıcı ID'leri gibi üçüncü taraf bir diff sitesine yüklenmesi istenmeyen bilgiler içerir.
Kararsız bir entegrasyon testi CI'de düştüğünde ve dizüstünüzde çalışan bir yanıtın Postman ekran görüntüsüyle build runner'dan gelen bozuk bir yanıtın CI log'una sahip olduğunuz an için tasarlandı. Tek seferlik bir araştırma için tam bir Pact contract test ayağa kaldırmak gereksizdir. İki metin paneli, bir diff ve sorunu genellikle bir dakikadan kısa sürede tek bir alana indirgersiniz.
Altta yatan diff motoru, compare-json aracımızı çalıştıranla aynıdır. Sadece API test akışı için çerçeveledik. Yanıtlarınız XML veya SOAP envelope ise, compare-xml sayfamız bunları halleder. Webhook log'u ya da audit trail gibi serbest biçimli metin karşılaştırıyorsanız, doğru yer compare-text aracımızdır.
API yanıt diff'i, ilişkili ama farklı iki test fikri arasındaki boşlukta durur. OpenAPI 3.1 şema diff'i, sözleşmenizin neyin değiştiğini söylediğini gösterir: yeni bir opsiyonel alan, yeniden adlandırılmış bir property, daha sıkı bir enum. Snapshot testleri (Jest snapshot, Vitest snapshot, pytest-snapshot) kodunuzun kayıtlı bir fixture'a karşı neyi ürettiğini söyler. Bu araç runtime tarafında durur. Ona iki gerçek yanıt body'si verirsiniz; şema değişikliğe izin verse de vermese de, snapshot fixture'unuz güncel olsa da olmasa da farklı olan her byte'ı gösterir.
Bu neden faydalı? Çünkü REST entegrasyon işinde en çok ısıran hatalar şema ihlalleri değildir. İnce sürüklenmelerdir: bir Jackson yükseltmesinden sonra bir tarihi sessizce ISO-8601'den Unix timestamp'e çeviren bir serializer, eksik bir alanı atlamak yerine null yaymaya başlayan bir Marshmallow şeması, bir middleware değişikliğinden sonra payload'u data envelope'una sarmaya başlayan bir DRF ViewSet. OpenAPI spec'i değişmedi. Snapshot güncellenmedi. Testler izolasyonda geçti. Entegrasyon koptu. Yanıt body diff'i bunların hepsini yakalar çünkü sözleşmeyi değil byte'ları umursar.
Volatil alanlar dikkat edilmesi gereken ana noktadır. Timestamp'ler, request ID'ler, trace ID'ler, sunucu tarafından üretilmiş UUID'ler ve sayfalama cursor'ları, anlamlı hiçbir şey değişmemiş olsa bile aynı endpoint'in iki yakalaması arasında farklı olur. Doğru hamle diff'ten önce normalleştirmektir: timestamp'leri bir placeholder ile değiştirin, trace ID'leri çıkarın, sıralaması sözleşme açısından önemli olmayan dizileri sıralayın. Pact gibi araçlar bunu matcher'larla halleder; bu araçta panelleri düzenleyerek yaparsınız. On saniye sürer ve gürültü tabanını ortadan kaldırır.
İki metin paneli, bir diff. Login yok, upload yok, kablolanacak proxy yok.
Endpoint'i curl, httpie, Postman, Insomnia ya da takımınızın kullandığı ne ise onunla çağırın. curl -s https://api.example.com/v1/users/123 | jq iyi bir başlangıçtır çünkü jq JSON'u biçimlendirerek diff'i çok daha okunaklı kılar. Body'yi kopyalayın (sadece JSON, header değil) ve sol panele yapıştırın. CI log'undan çekiyorsanız çoğu logger'ın eklediği timestamp önekini çıkarın ki diff gerçek payload'a inse.
Karşılaştırma kaynağını çağırın: diğer ortam, diğer API sürümü, diğer satıcı. Aynı yakalama biçimi, aynı pretty-print adımı. Sağ panele yapıştırın. Bir yakalama kayıtlı bir fixture'dan (vcrpy, pollyjs, MSW, nock) ve diğeri canlıysa, önce belirgin volatil alanları normalleştirin: request_id'yi temizleyin, timestamp'leri bir sabitle değiştirin, body'ye sızmış trace header'ları kaldırın. Kalan diff gerçek sinyaldir.
Silmeler solda kırmızı üstü çizili olarak; eklemeler sağda yeşil olarak görünür. Her başlıktaki değişiklik sayaçları diff'in kaç ayrı edit bulduğunu söyler. Önce üç şeye odaklanın: status string değişiklikleri, eksik veya eklenmiş key'ler ve değer tipi değişiklikleri (string'ten number'a, object'ten null'a). Bu üç kategori neredeyse her gerçek API regresyonunu kapsar. Format ve sıralama değişiklikleri, consumer'ınız onlara bağlı değilse genellikle gürültüdür.
Bir test yerelde geçer, CI'de düşer. Yerel Postman çalıştırmanızla yakalanan yanıt ve CI build agent'ı tarafından yakalanan yanıt elinizde (çoğu CI sistemi verbose flag ile request/response dump edebilir). İkisini de diff aracına yapıştırın. On seferden dokuzunda fark çevreseldir: farklı feature flag, eski fixture, runner'da saat dilimi farkı. Geri kalan biri gerçek bir hatadır ve onu az önce belirli bir alana indirgediniz.
Repo'nuzda testler için üçüncü taraf bir API'yi mock'layan, commit edilmiş bir fixture dosyası var. Upstream sağlayıcı az önce yeni bir minor sürüm yayımladı. Canlı endpoint'i curl ile çağırın, o yanıtı fixture'ınızın yanına yapıştırın ve hangi alanların kaydığını tam olarak görün. Bu, VCR tarzı replay araçlarının otomatikleştirdiğinin manuel sürümüdür. Tüm test paketinizi yeniden kaydetmeden tek bir fixture'ı güncellemek istediğinizde işe yarar.
Dahili bir API'nin v2'sini yayımlamak üzeresiniz. Production'da hâlâ bir v1 client var. Hem /v1/orders/42'yi hem de /v2/orders/42'yi çağırın ve yanıtların diff'ini alın. Kaldırılan herhangi bir alan, yeniden adlandırılmış herhangi bir key, herhangi bir değer tipi değişikliği v1 client için breaking change'tir. Yeni eklenen herhangi bir alan additive ve güvenlidir. Bu, fakirin consumer-driven contract test'idir; düzinelerce endpoint'e ölçeklenmez ama bir-iki endpoint için hızlı bir sağlık kontrolü olarak iş görür.
Takımınız Jackson, Marshmallow, DRF veya benzeri bir serileştirme katmanını yükseltti. Testler geçiyor. Sonra bir downstream consumer parser'ının takıldığını bildiriyor. Aynı endpoint yanıtını eski branch'te ve yeni branch'te yakalayıp diff alın. Yaygın bulgular: bir tarih formatı 2026-05-09T10:00:00Z'den Unix timestamp'e döndü, ondalıklar son sıfırlarını yitirdi, bir enum string yerine integer olarak serialize edilmeye başladı veya daha önce atlanan null alanlar payload'da görünmeye başladı.
Aynı event tipinin Stripe webhook V1 ve V2'si neredeyse aynı görünür ve hiç de öyle değildir. GitHub webhook event payload'ları için API sürümleri arasında, ve Slack event subscription'ları için scope'lar arasında da öyle. Her birinden bir örnek payload'u diff aracına yapıştırın; yeniden adlandırılan alanları, taşınan iç içe nesneleri ve yeni metadata bloklarını görün. Bu, iki sağlayıcının doc sayfalarını yan yana okumaktan, özellikle de doc'ların pratikte hangi alanların gerçekten göründüğünü es geçtiği durumlarda, daha hızlıdır.
Klasik deploy baş ağrısı. Aynı client isteği staging ve production'dan ince biçimde farklı JSON döndürüyor. İkisini de yakalayın, ikisini de yapıştırın; fark genellikle bir config flag, eksik bir feature gate veya eski bir cache yanıtıdır. Aynı şey çoklu bölge debugging'i (us-east-1 ile eu-west-1'in farklı veri döndürmesi), CDN cache sorunları (Cloudflare eski bir body cache'lemiş) ve bir yazma işleminin her yere yayılmadığı read-replica gecikmesi için de geçerlidir.
Bir yanıt body diff'inin test framework'ünüzün, OpenAPI aracınızın ya da gözlerinizin söyleyeceğiyle uyuşmadığı durumlar. Diff'in gerçek bir hata bulduğunu varsaymadan önce göz atmaya değer.
| Topic | What this tool does |
|---|---|
| Volatil alanlar (timestamp, ID) | created_at, updated_at, request_id, trace_id, sunucu tarafından üretilmiş UUID'ler ve sayfalama cursor'ları iki yakalama arasında her zaman farklı olur. jq 'del(...)' ile normalleştirin, bir sabitle değiştirin ya da diff öncesi düzenleyip kaldırın. Gerçekten umursadığınız sinyal başka bir yerde. |
| null - eksik key | {"foo": null} ve {} JSON'da farklıdır ve birçok serializer'ın (Marshmallow, Jackson, System.Text.Json) ikisi arasında geçen ayarları vardır. Diff bunu su yüzüne çıkarır. Bazı client'lar bunları eşdeğer sayar, bazıları saymaz; doğru cevap consumer'ınızın ne yaptığıdır ve bu yüzden serializer yükseltmesinin ardından sık görülen bir regresyon kaynağıdır. |
| Key sıralaması | RFC 8259, JSON nesnelerini sırasız olarak tanımlar. Anlamsal olarak özdeş ama key sırası farklı iki yanıt burada diff olarak görünür çünkü metin karşılaştırması sıraya duyarlıdır. Sıraya duyarsız diff istiyorsanız iki tarafı da önce jq --sort-keys ile ön-sıralayın. Sıraya bağımlı nadir consumer'a (bazı imza akışları, bazı eski parser'lar) dikkat edin. |
| Dizi sıralaması | JSON'da diziler sıralıdır ama birçok API, sırası aslında sözleşmesel olmayan diziler döndürür: izinler listesi, feature flag'ler listesi, webhook abonelikleri listesi. Hiçbir consumer önemsemiyor olsa bile diff yeniden sıralanmış bir diziyi değişiklik olarak işaretler. Yeniden sıralama sizin domain'inizde zararsızsa, diff öncesi iki tarafı da kararlı bir key üzerinden sıralayın. |
| JSON.parse katılığı | Diff girdinizi opak metin olarak işler. Yakalamalarınızdan birinde sondaki virgül, tırnaksız bir key veya yorum varsa (sıkı JSON'da hepsi yasaklıdır), diff yine de çalışır ama olması gerektiğinden daha gürültülü görünür. İki yakalamayı da önce jq .'den geçirip yeniden biçimlendirin ve geçersiz girdiyi reddedin. jq sıkı bir RFC 8259 parser'ı kullanır. |
| Yanıt sarmalaması (data envelope - düz) | Birçok API payload'u {"data": ...} envelope'una sarar, bazen yanına meta, links veya included ekler (JSON:API ve benzerleri). Düzden sarmalanmışa (ya da tam tersi) bir geçiş, diff'te anında görünen bir breaking change'dir; ama altta yatan kayıt aynı göründüğü için şema review'ında kolayca gözden kaçar. |
| Sayfalama cursor değişiklikleri | Cursor tabanlı sayfalama, her çağrıda değişmek üzere tasarlanmış opak token'lar (next_cursor, after, page_token) kullanır. Daima diff olarak görünürler. Karşılaştırma öncesi çıkarın ya da yalnızca data dizisinin içeriğini karşılaştırıp sayfalama bloğunu tamamen yok sayın. |
| Hata yanıt formatları | Hata body'leri vahşi batıdır. Bazı API'ler düz bir {"error": "..."} döndürür, bazıları type, title, status, detail, instance içeren RFC 7807 Problem Details döndürür ve bazıları satıcıya özgü bir biçim döndürür. Özel bir biçimden RFC 7807'ye geçiş büyük bir diff üretir ve çoğunlukla bir iyileştirmedir; ters yönde bir geçiş erken yakalanmaya değer bir regresyondur. |
Postman'in Collection Runner'ı içinde bir yanıt karşılaştırma görünümü ve tek tek yanıtlar için bir Visualize özelliği var. Postman içinde yaşıyor ve yanıtlarınız zaten Postman geçmiş öğeleri olarak kaydediliyorsa her ikisi de iyi. Bu araç sağlayıcıdan bağımsızdır. Postman, Insomnia, curl, httpie, bir CI log'u, bir Stack Overflow snippet'i ya da bir meslektaşın Slack mesajından yapıştırabilirsiniz. Hesap yok, workspace yok, sync yok. Araçlar arası tek seferlik karşılaştırmalar için bu daha hızlıdır. Tek bir platformda takım paylaşımlı API testleri için Postman'in kendi özelliği yeterlidir.
Pragmatik hamle diff öncesi normalleştirmektir. İki yapıştırmayı da panellerde açın, ardından volatil alanları doğrudan düzenleyin: timestamp'leri sabit bir string ile değiştirin, request_id ve trace_id değerlerini çıkarın, her çağrıda değişen sayfalama cursor'larını silin. Diff yalnızca kalan farkları vurgular ve gerçekten önemli olanlar onlardır. Aynı endpoint'in tekrarlı karşılaştırmaları için, yanıtı yapıştırmadan önce jq ile bir delete filtresinden de geçirebilirsiniz (jq 'del(.meta.request_id)').
Şema diff'i sözleşmeleri karşılaştırır: POST /orders'a opsiyonel bir discount_code alanı eklendiğini ya da status enum'una yeni bir değer geldiğini söyler. oasdiff veya Spectral gibi OpenAPI farkında araçlar bu işi iyi yapar. Bu araç gerçek yanıt body'lerini karşılaştırır. İkisi tamamlayıcıdır. Şema diff sözleşme değişikliklerini yakalar; yanıt diff sözleşme ile gerçeklik arasındaki sürüklenmeyi yakalar; serileştirme hataları, ortam uyuşmazlıkları ve eski fixture'lar tam orada saklanır.
Pratikte evet, her tarafta birkaç bin satır biçimlendirilmiş JSON'a kadar. Ötesinde, semantik temizlikli karakter düzeyinde diff yavaşlar çünkü bir sunucuda değil tarayıcınızda çalışır. Çok büyük payload'lar için (10.000 kayıtlık bir sayfalı dump düşünün) doğru yaklaşım, yanıtı kayıt veya üst düzey key bazında küçük parçalara bölüp her parçayı ayrı ayrı diff almaktır. Ya da saf hız için komut satırında jd veya diff <(jq . a.json) <(jq . b.json) ile yapısal bir diff çalıştırın.
Doğrudan değil. Bu sayfa JSON için ayarlandı, modern REST ve webhook payload'larının çoğu JSON kullanır. XML, SOAP envelope, RSS veya POM tarzı yapılandırma diff'i almanız gerekiyorsa doğru yer compare-xml aracımızdır; girinti ve namespace biçimlendirmesini doğru yönetir. Header ve body'nin karıştığı ham yanıt body'leri ya da düz metin API'ler (bazı eski sistemler hâlâ text/plain döndürür) için compare-text bir yapı dayatmadan işi halleder.
Yapıştırdığınız key sırasını korur. JSON nesneleri RFC 8259'a göre resmen sırasızdır, dolayısıyla key'leri farklı sırada olan anlamsal olarak özdeş iki yanıt bu araçta diff olarak görünür. Sırayı yoksaymak istiyorsanız önce iki tarafı da jq --sort-keys veya muadilinden geçirin. Çoğu client key sırasına bağlı değildir, dolayısıyla sıralı key normalleştirme yanıt karşılaştırması için güvenli bir varsayılandır; ama bazı eski consumer'ların (eski XML-JSON köprüleri, belirli dijital imza akışları) sıraya bağlı olduğunu unutmayın.
API yanıt payload'ları sızdırmak istemediğiniz şeyleri sıkça içerir. Müşteri e-posta adresleri. Dahili kullanıcı ID'leri. Oturum token'ları. Yanlışlıkla bir body alanına düşmüş Auth bearer token'ları. Stripe müşteri ID'leri. Webhook gizli anahtarları. Ad, adres ve telefon numarası gibi PII alanları. Bunlardan birini bulutta barınan bir diff hizmetine yapıştırmak başlı başına bir veri işleme olayıdır ve sektörünüze bağlı olarak SOC 2 kontrollerinizi, GDPR veri işleme sözleşmelerinizi veya HIPAA Business Associate Agreement'larınızı ihlal edebilir. Bu araç tamamen tarayıcınızda çalışır. Hiçbir şey yüklenmez, loglanmaz veya herhangi bir üçüncü taraf hizmete gönderilmez. Diff, vurgulama ve render'ın tamamı sizin makinenizde çalışır. İddiayı doğrulamak basittir: tarayıcınızın DevTools'unu açın, Network sekmesine geçin, iki yanıtı yapıştırın ve izleyin. Karşılaştırma sırasında dışa giden istek yoktur. Daha geniş API tasarımı ve güvenlik rehberi için Microsoft'un API design best practices belgesi sağlam bir referanstır.