{"id":71,"date":"2026-10-25T08:05:00","date_gmt":"2026-10-25T08:05:00","guid":{"rendered":"https:\/\/www.akifsen.com.tr\/blog\/2026\/10\/25\/api-backward-compatibility-versioning\/"},"modified":"2026-10-25T08:05:00","modified_gmt":"2026-10-25T08:05:00","slug":"api-backward-compatibility-versioning","status":"publish","type":"post","link":"https:\/\/www.akifsen.com.tr\/blog\/2026\/10\/25\/api-backward-compatibility-versioning\/","title":{"rendered":"API Versiyonlamadan \u00d6nce Geriye Uyumlulu\u011fu Konu\u015fal\u0131m"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">Bir API&#8217;de de\u011fi\u015fiklik ihtiyac\u0131 do\u011fdu\u011funda s\u0131k duyulan c\u00fcmle \u015fudur:<\/p>\n\n\n\n<blockquote class=\"wp-block-quote is-layout-flow wp-block-quote-is-layout-flow\">\n<p class=\"wp-block-paragraph\">Bunu v2&#8217;de yapar\u0131z.<\/p>\n<\/blockquote>\n\n\n\n<p class=\"wp-block-paragraph\">Sonra <code>\/v2<\/code> yolu a\u00e7\u0131l\u0131r. Bir s\u00fcre iki versiyon birlikte ya\u015far. Eski client&#8217;lar <code>\/v1<\/code> kullanmaya devam eder. Kimse onlar\u0131 ta\u015f\u0131maz. \u0130ki y\u0131l sonra <code>\/v3<\/code> gelir ve backend \u00fc\u00e7 farkl\u0131 s\u00f6zle\u015fmeyi ayn\u0131 anda desteklemek zorunda kal\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Versiyonlama gerekli bir ara\u00e7.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Ama \u00e7o\u011fu durumda as\u0131l ihtiya\u00e7 versiyonlamak de\u011fil, k\u0131rmadan de\u011fi\u015ftirebilmek.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Breaking change nedir?<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Bir de\u011fi\u015fikli\u011fin breaking olup olmad\u0131\u011f\u0131n\u0131 belirleyen \u015fey, mevcut bir client&#8217;\u0131n hi\u00e7bir de\u011fi\u015fiklik yapmadan \u00e7al\u0131\u015fmaya devam edip etmedi\u011fidir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Genellikle g\u00fcvenli olanlar:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Response&#8217;a yeni ve opsiyonel bir alan eklemek<\/li>\n\n\n<li>Yeni bir endpoint eklemek<\/li>\n\n\n<li>Request&#8217;e varsay\u0131lan de\u011feri olan opsiyonel bir parametre eklemek<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Genellikle k\u0131ranlar:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Bir alan\u0131 silmek veya yeniden adland\u0131rmak<\/li>\n\n\n<li>Bir alan\u0131n tipini de\u011fi\u015ftirmek<\/li>\n\n\n<li>Opsiyonel bir request alan\u0131n\u0131 zorunlu yapmak<\/li>\n\n\n<li>Hata kodlar\u0131n\u0131n veya status code&#8217;lar\u0131n anlam\u0131n\u0131 de\u011fi\u015ftirmek<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Bir de gri alan var. Enum&#8217;a yeni bir de\u011fer eklemek teknik olarak bir ekleme. Ama <code>switch<\/code> ifadesinde bilinmeyen de\u011feri beklemeyen bir client i\u00e7in breaking change. Mobil uygulamalarda \u00f6zellikle can yak\u0131c\u0131, \u00e7\u00fcnk\u00fc eski versiyonlar y\u0131llarca kullan\u0131c\u0131lar\u0131n telefonlar\u0131nda kalabiliyor.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Tolerant reader<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Geriye uyumluluk sadece API sa\u011flay\u0131c\u0131s\u0131n\u0131n sorumlulu\u011fu de\u011fil.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Client&#8217;lar\u0131n da bilmedi\u011fi alanlar\u0131 g\u00f6rmezden gelmesi gerekir. Jackson&#8217;\u0131n varsay\u0131lan ayarlar\u0131nda bilinmeyen bir alan exception&#8217;a yol a\u00e7abiliyor:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>spring.jackson.deserialization.fail-on-unknown-properties=false<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">Spring Boot bu de\u011feri zaten false olarak ayarl\u0131yor ama Jackson&#8217;\u0131 do\u011frudan kullanan kodda bu ayr\u0131ca kontrol edilmeli.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Enum&#8217;lar i\u00e7in de bilinmeyen de\u011ferler bir <code>UNKNOWN<\/code> sabitine d\u00fc\u015f\u00fcr\u00fclebilir. Bu yakla\u015f\u0131ma tolerant reader deniyor. Sa\u011flay\u0131c\u0131n\u0131n API&#8217;yi geni\u015fletmesine izin verir.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Expand and contract, API versiyonu<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Bir alan\u0131 yeniden adland\u0131rmak gerekiyorsa, bunu tek ad\u0131mda yapmak zorunda de\u011filiz.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>{\n  \"name\": \"Akif\",\n  \"fullName\": \"Akif \u015een\"\n}<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\">\u00d6nce yeni alan eklenir. Eski alan bir s\u00fcre birlikte d\u00f6ner ve dok\u00fcmantasyonda deprecated olarak i\u015faretlenir. Client&#8217;lar yeni alana ge\u00e7er. Eski alan\u0131n kullan\u0131m\u0131 \u00f6l\u00e7\u00fcl\u00fcr ve s\u0131f\u0131ra yakla\u015ft\u0131\u011f\u0131nda kald\u0131r\u0131l\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Bu, veritaban\u0131 migration&#8217;lar\u0131nda kullan\u0131lan expand and contract yakla\u015f\u0131m\u0131n\u0131n API kar\u015f\u0131l\u0131\u011f\u0131.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Kritik k\u0131s\u0131m \u00f6l\u00e7mek. Eski alan\u0131n veya endpoint&#8217;in h\u00e2l\u00e2 kim taraf\u0131ndan kullan\u0131ld\u0131\u011f\u0131n\u0131 bilmeden kald\u0131rmak, tahmine dayal\u0131 bir karar olur. Request loglar\u0131nda client kimli\u011fi veya user agent tutmak bu y\u00fczden \u00f6nemli.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Kald\u0131rma tarihi yakla\u015f\u0131rken <code>Deprecation<\/code> ve <code>Sunset<\/code> header&#8217;lar\u0131 ile client&#8217;lara makine taraf\u0131ndan okunabilir bir uyar\u0131 da verilebilir.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Versiyon ger\u00e7ekten gerekti\u011finde<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Bazen k\u0131rmadan ilerlemek m\u00fcmk\u00fcn de\u011fildir. Kaynak modeli k\u00f6kten de\u011fi\u015fmi\u015ftir veya eski davran\u0131\u015f\u0131 koruman\u0131n maliyeti \u00e7ok y\u00fcksektir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Bu durumda versiyonlama do\u011fru ara\u00e7t\u0131r. URL&#8217;de (<code>\/v2\/orders<\/code>), header&#8217;da veya media type&#8217;ta yap\u0131labilir. URL yakla\u015f\u0131m\u0131 daha az zarif ama en g\u00f6r\u00fcn\u00fcr ve en kolay debug edilebilir olan\u0131. Ben genellikle onu tercih ediyorum.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Ama versiyon a\u00e7arken iki \u015feyi ba\u015ftan planlamak gerekiyor: eski versiyonun ne zaman kapanaca\u011f\u0131 ve client&#8217;lar\u0131n nas\u0131l ta\u015f\u0131naca\u011f\u0131. Bu ikisi planlanmadan a\u00e7\u0131lan her yeni versiyon, bak\u0131m\u0131 s\u00fcresiz uzayan bir s\u00f6zle\u015fme demek.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Contract test<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">API&#8217;nin istemeden k\u0131r\u0131lmas\u0131n\u0131 \u00f6nlemenin en etkili yolu, s\u00f6zle\u015fmeyi test etmektir.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">OpenAPI \u015femas\u0131n\u0131 CI&#8217;da bir \u00f6nceki versiyonla kar\u015f\u0131la\u015ft\u0131ran ara\u00e7lar, silinen alanlar\u0131 veya de\u011fi\u015fen tipleri merge&#8217;den \u00f6nce yakalayabiliyor. Consumer-driven contract testing ise client&#8217;lar\u0131n ger\u00e7ekten hangi alanlara ba\u011f\u0131ml\u0131 oldu\u011funu a\u00e7\u0131k\u00e7a kaydediyor.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">\u0130yi bir API, tasarland\u0131\u011f\u0131 ilk g\u00fcn de\u011fil, be\u015finci kez de\u011fi\u015ftirildi\u011finde anla\u015f\u0131l\u0131r.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">As\u0131l soru &#8220;nas\u0131l versiyonlar\u0131z?&#8221; de\u011fil, &#8220;nas\u0131l kimseyi k\u0131rmadan de\u011fi\u015ftiririz?&#8221; olmal\u0131.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>\/v2 a\u00e7mak \u00e7o\u011fu zaman problemi \u00e7\u00f6zmez, sadece ertelemeye yarar. Hangi de\u011fi\u015fiklik breaking change say\u0131l\u0131r, tolerant reader nedir ve API nas\u0131l k\u0131rmadan evrilir?<\/p>\n","protected":false},"author":1,"featured_media":70,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[9],"tags":[],"class_list":["post-71","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-api-tasarimi"],"_links":{"self":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts\/71","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/comments?post=71"}],"version-history":[{"count":0,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/posts\/71\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/media\/70"}],"wp:attachment":[{"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/media?parent=71"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/categories?post=71"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.akifsen.com.tr\/blog\/wp-json\/wp\/v2\/tags?post=71"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}