camelCase mi snake_case mi: JSON Alan Adları İçin Hangisi Kullanılmalı

Dağıtık sistemlerin mimari tasarımında, API'ler sadece sistem etkileşimi için birer kanal değildir; farklı teknoloji yığınlarını, organizasyonel kültürleri ve hatta geliştirme dönemlerini birbirine bağlayan sözleşmelerdir. RESTful API'lerin tasarım detaylarında, görünüşte önemsiz bir konu bitmek bilmeyen bir tartışma yaratır: JSON alan adları camelCase mi yoksa snake_case mi kullanmalı?

Bu sadece estetik bir tercih değildir. Arka uç kalıcılık katmanları ile ön uç sunum katmanları arasındaki "empedans uyumsuzluğunu" ele alır; serileştirme performansı, ağ iletim verimliliği, Geliştirici Deneyimi (DX) ve bilişsel psikolojiyi içerir.

Programlama dillerinin tarihçesine, temel teknik uygulama mekanizmalarına ve Google ve Stripe gibi sektör devlerinin mimari kararlarına dayanarak, bu makale uzman düzeyinde bir karar rehberi sunmaktadır.

1. Tarihsel Kökenler: Semiyotik Bir Tercih

Bu tartışmayı anlamak için bilgisayar dillerinin evrimini takip etmeliyiz. Adlandırma kuralları birdenbire ortaya çıkmadı; belirli dönemlerin donanım sınırlamalarının ve topluluk kültürlerinin ürünleridir.

snake_case'in Kökeni: C ve Unix Felsefesi

snake_case'in (örn. user_id) popülaritesi 1970'lerde C ve Unix'e dayanmaktadır. İlk klavyeler (Teletype Model 33 gibi) shift tuşlarına sahip olsa da, birçok erken derleyici büyük/küçük harfe duyarsızdı. Düşük çözünürlüklü ekranlarda kelimeleri net bir şekilde ayırmak için programcılar doğal dildeki boşlukları simüle etmek amacıyla alt çizgi (underscore) kullandılar. Bu alışkanlık SQL veritabanı standartlarında derinlemesine kök saldı. Bugüne kadar, PostgreSQL ve MySQL için varsayılan sütun adlandırma stili snake_case olarak kalmaya devam ediyor ve bu durum, API'ler ile veritabanları arasındaki gelecekteki eşleme sürtünmesinin temelini oluşturuyor.

camelCase'in Yükselişi: Java ve JavaScript Hegemonyası

camelCase (örn. userId), Nesne Yönelimli Programlama (Smalltalk, C++, Java) ile birlikte yükseldi. Java, "sınıflar için PascalCase, metotlar/değişkenler için camelCase" endüstri standardını oluşturdu. Belirleyici dönüm noktası **JavaScript**'in doğuşu oldu. JSON, JS nesne değişmezlerinden türetilmiş olsa da, JS standart kütüphanesi (örn. getElementById) genel olarak camelCase'i benimsedi. AJAX ve JSON, baskın veri alışveriş formatları olarak XML'in yerini aldığında, camelCase Web alanında "yerel" statü kazandı.

2. Temel Çatışma: Teknoloji Yığınlarının Empedans Uyumsuzluğu

Veriler farklı diller arasında akarken, kaçınılmaz olarak "empedans uyumsuzluğu" ile karşılaşır.

Arka Uç Bakış Açısı (Python/Ruby/SQL)

Arka uçta, Python (PEP 8) ve Ruby toplulukları şiddetle snake_case kullanılmasını önermektedir.

• Python/Django/FastAPI: Pydantic modelleriniz genellikle doğrudan veritabanı tablo yapılarına karşılık gelir:

class UserProfile(BaseModel):
    first_name: str  # Python kuralı
    last_name: str

API camelCase'i zorunlu kılarsa, serileştirme katmanında takma adlar veya dönüştürücüler yapılandırmanız gerekir. Bu mümkün olsa da, bir eşleme mantığı katmanı ekler.

• SQL Veritabanları: Çoğu veritabanı sütun adı snake_case kullanır. API camelCase kullanıyorsa, ORM katmanının dönüştürmeyi tutarlı bir şekilde ele alması gerekir.
• Stripe'ın Tercihi: Stripe ve GitHub'ın snake_case'i kesin olarak seçmesinin nedeni, büyük ölçüde ilk mimarilerinin Ruby yığını üzerine inşa edilmiş olmasıdır. Dahili modelleri doğrudan ifşa etmek, arka uç tutarlılığını sağlamıştır.

Ön Uç Bakış Açısı (JavaScript/TypeScript)

Tarayıcıda, camelCase mutlak egemendir.

• Kod Stili Parçalanması: Bir API snake_case döndürürse, ön uç kodu tutarsız hale gelir:

const user = await fetchUser();
console.log(user.first_name); // ESLint camelcase kuralını ihlal eder
render(user.email_address);

ESLint bunu bir uyarı olarak işaretleyecek ve geliştiricileri kuralı devre dışı bırakmaya veya veriyi hemen aldıktan sonra dönüştürmeye zorlayacaktır.

• Yapı Bozma Sıkıntısı: Modern JS/TS geliştirmesinde, nesne yapı bozma (object destructuring) her yerdedir. Alanlar snake_case ise, yerel kapsamı kirletmemek için yapı bozma sırasında yeniden adlandırılmaları gerekir:

// Uzun yeniden adlandırma
const { first_name: firstName, last_name: lastName } = response.data;

Bu, taslak kodunu ve hata olasılığını artırır.

3. Performans Mitleri: Serileştirme ve Ağ İletimi

Performans konusunda iki yaygın mit bulunmaktadır: "Alan adı dönüştürme çok yavaş" ve "Alt çizgiler veri yükü boyutunu artırır." Verilerle açıklayalım.

Mit 1: Çalışma Zamanı Dönüştürme Yükü

• Dinamik Diller: Python veya Ruby'de, her istekte düzenli ifade (regex) değişimi yoluyla alan adlarını dönüştürmek CPU tüketir. Ancak, modern çerçeveler (Rust'ta yeniden yazılan Pydantic v2 gibi) önceden hesaplanmış Şema eşlemeleri aracılığıyla bu yükü en aza indirir.
• Statik Diller (Go/Java/Rust): Bu aslında "sıfır maliyetlidir". Go'nun yapı etiketleri (json:"firstName") veya Java Jackson'ın eşleme önbellekleri derleme veya başlangıç zamanında belirlenir. Çalışma zamanı yürütmesi, dinamik hesaplama değil, basit bayt kopyalamayı içerir.

Not: Ön uçta (tarayıcının ana iş parçacığı) interceptor'lar (örn. Axios) kullanarak asla genel özyinelemeli dönüşüm yapmayın. Büyük yanıtlar için bu, sayfa takılmalarına ve bellek tüketimine neden olur. Sonuç: Dönüştürmeyi arka uç halletmelidir.

Mit 2: İletim Boyutu ve Sıkıştırma

Teorik olarak, first_name, firstName'den bir bayt daha uzundur. Ancak, Gzip veya Brotli sıkıştırma etkinleştirildiğinde (standart HTTP yapılandırması), bu fark neredeyse tamamen ortadan kalkar.

• Prensip: Sıkıştırma algoritmaları "yinelenen dize referanslamasına" dayanır. Bir JSON dizisinde, anahtarlar oldukça tekrarlayıcıdır. Algoritma, ilk karşılaştığında first_name'i bir sözlükte saklar ve sonraki geçişleri küçük bir işaretçiyle değiştirir.
• Karşılaştırmalar: Testler, Gzip seviye 6 altında, iki stil arasındaki boyut farkının genellikle %0,5 ila %1 arasında olduğunu göstermektedir. Verileri uydu bağlantıları üzerinden iletmediğiniz sürece, bu bir sorun değildir.

4. Geliştirici Deneyimi (DX) ve Bilişsel Psikoloji

Mimari sadece makinelerle ilgili değildir; insanlarla ilgilidir.

• snake_case'in Okunabilirliği: Bilişsel psikoloji, alt çizgilerin net görsel ayrım sağladığını öne sürmektedir. parse_db_xml, özellikle ardışık kısaltmalarla (örn. XMLHTTPRequest'e karşı XmlHttpRequest) uğraşırken beynimiz tarafından parseDbXml'den daha hızlı ayrıştırılır. Stripe'ın belgelerinin oldukça okunabilir kabul edilmesinin nedenlerinden biri budur.
• camelCase'in Tutarlılığı: Tam yığın tutarlılığının getirdiği akış durumu daha kritiktir. Tam yığın JS/TS ekipleri için, ön uçta ve arka uçta camelCase kullanmak, tür tanımlarının (Arayüz/Zod Şeması) doğrudan yeniden kullanılmasını sağlar ve "zihinsel çeviri" bilişsel yükünü tamamen ortadan kaldırır.

5. Endüstri Standartları ve Gerekçesi

6. Derinlemesine Mimari Tavsiye: Ayırma ve DTO'lar

Yaygın bir anti-kalıp "Doğrudan Geçiş"tir: veritabanı varlıklarını doğrudan serileştirerek geri döndürmek.

• Bunu yaparsanız ve DB sütunlarınız snake_case ise, API'niz snake_case olur.
• Risk: Bu, bilgi gizleme prensibini ihlal eder, tablo yapılarını ifşa eder ve API ile DB arasında güçlü bir bağımlılık (coupling) yaratır. DB yeniden adlandırılırsa, API bozulur.

En İyi Uygulama: Bir DTO (Veri Aktarım Nesnesi) katmanı tanıtın. Temel veritabanının nasıl adlandırıldığından bağımsız olarak, bağımsız bir API sözleşmesi (DTO) tanımlamalısınız. Bir DTO tanımladığınıza göre, neden Web standartlarına uymak için onu camelCase olarak tanımlamayasınız? Modern eşleme araçları (MapStruct, AutoMapper, Pydantic) bu dönüşümü zahmetsizce halleder.

7. Geleceğe Bakış: GraphQL ve gRPC

GraphQL: Topluluk neredeyse %100 oranında camelCase'i benimsemektedir. Ekibiniz gelecekte GraphQL'i tanıtmayı planlıyorsa, REST API'lerini şimdi camelCase ile tasarlamak akıllıca bir "ileri uyumluluk" stratejisidir.

gRPC: Protobuf standardı şunu belirtir: .proto dosyaları alan tanımları için snake_case kullanır, ancak JSON'a eşlendiğinde camelCase'e dönüştürülmeleri gerekir. Bu, Google'ın çok dilli ortamlar için standart çözümüdür.

8. Özet ve Karar Matrisi

Mutlak doğru veya yanlış yoktur, sadece tavizler vardır. İşte nihai karar çerçevesi:

Önerilen: Varsayılan olarak camelCase

Web/Uygulama istemcilerine yönelik yeni, genel amaçlı RESTful API'lerin büyük çoğunluğu için, camelCase şiddetle tavsiye edilir.

Neden: JSON/JavaScript/TypeScript'in hakimiyetiyle uyum sağlamak, tüketicilerin %90'ının alışkanlıklarını benimsemek.

Araçlar: OpenAPI kod üreteçlerinden, Swagger UI'dan ve modern IDE'lerden en iyi desteği alın.

Ne Zaman snake_case Kullanmalı?

1. Belirli Tüketiciler: API'nin birincil kullanıcıları Python veri bilimcileri veya sistem operasyonları (Curl/Bash) ise.

2. Eski Sistemler: Mevcut API'ler zaten snake_case'dir. Tutarlılık > En İyi Uygulama. Aynı sistem içinde stilleri karıştırmayın.

3. Arka Uç Hız Aşırıcılığı: DTO katmanını koruyacak kaynaklar olmadan Python/Ruby kullanmak, veritabanı modellerini doğrudan geçirmek.

Karar Tablosu

API tasarımının özü empatidir. Web API'leri bağlamında, karmaşıklığı arka uçta (eşlemeyi ele alarak) kapsüllemek ve kolaylığı kullanıcıya bırakmak (JS alışkanlıklarına uymak), daha fazla profesyonelliği yansıtan tercihtir.