SOAP'tan REST'e migration: 18 ayda yaptığım 3 proje

SOAP 2000’lerin dünyasından kalma ama hala pek çok kurumsal sistemde canlı. Son 18 ayda 3 farklı projede SOAP backend’ini REST’e taşıdım: bir bank entegrasyonu, bir ERP sistemi, bir devlet kurumu API’si. Her birinde farklı zorluklar çıktı ama ortak bir kalıp oturdu.

Bu yazıda migration yapmayı düşünenler için pratik notlar.

SOAP’ın gerçek sorunu

SOAP’ın teknik olarak kötü bir protokol olduğunu söylemiyorum. XML envelope, WSDL contract, WS-* standartları enterprise ortamda anlamlı idi. Asıl sorun bugünkü ekosistemde:

Modern client’lar (mobil, SPA) JSON bekliyor, XML parse etmek ekstra iş
Developer experience berbat: WSDL’den stub üretmek, namespace çakışmaları, soap fault’larla uğraşmak
Gözlemlenebilirlik zayıf: postman’de debug etmek zor, cURL’de uzun komutlar
Ekipte SOAP bilen azalıyor, işe alımlarda soruna dönüşüyor

Big bang vs strangler fig

İlk projede big bang yaptım. Eski sistem kapatıldı, yenisi açıldı. Bir geceyi stress ile geçirdim, rollback senaryosu belirsizdi, ertesi sabah 3 entegrasyon breakdown yaşandı. Öğrendiğim ders: büyük enterprise sistemlerde big bang işlemez.

Diğer 2 projede strangler fig pattern uyguladım: yeni REST API’yi eskinin önüne gateway olarak koydum, client’lar tek tek migre oldu, eski SOAP endpoint’i consumer kalmayınca devre dışı bırakıldı.

Gateway’in avantajı: iki protokolü de konuşabilir, translation katmanı olarak çalışır, monitoring ile geçiş hızını gözlemlersiniz.

Gateway katmanı tasarımı

Gateway şu 3 işi yapıyor:

Protocol translation: REST request gelir, SOAP envelope’a sararak backend’e yollar, yanıtı JSON’a çevirir
Auth bridging: REST’te OAuth 2.0 Bearer, SOAP backend WS-Security bekler, gateway iki kimliği birbirine mapleyen katman
Routing: REST endpoint path’ine göre hangi SOAP operation’a gideceğini belirler

Gateway çözümü olarak enterprise world’de Apigee, Kong, MuleSoft kullanılıyor. Biz mevcut projelerde hafif NGINX + custom microservice ile çözdük, yılda onbinlerce dolar lisans ödemeden. Volume arttıkça commercial ürünlere geçiş gerekebilir.

XML to JSON mapping

En sinsi iş XML envelope’ı düzgün JSON’a çevirmek. XML’de namespace’ler, attribute’lar, CDATA’lar var. JSON düz yapı bekliyor.

Köşeli parantezler vs obje: XML’de tek eleman da aynı tag ile temsil edilir, JSON’da tek elemanı obje, çoğul elemanı array olarak döndürmek tercih edilir. Gateway’in mapping mantığı bu ayrımı otomatik yapmalı.

Attribute’lar: XML attribute’ları JSON’da property olarak nasıl temsil edilecek? Convention seçin ve tüm API’de tutarlı olun. Biz @ prefix ile attribute, normal isimle eleman ayrımı yaptık.

Tarih formatları: SOAP xsd:dateTime ISO 8601 ama timezone olmadan, JSON tarafında ISO 8601 UTC istiyoruz. Dönüşüm gerekli.

Error handling farklılığı

SOAP fault ile REST HTTP status code dünyaları farklı:

SOAP: 200 OK döner, body içinde ile hatayı bildirir
REST: 4xx/5xx HTTP status + JSON error body

Gateway SOAP fault’u parse edip uygun REST error’a çevirmeli. Biz şöyle mapledik:

FaultCode: Client.Authentication → 401
FaultCode: Client.Authorization → 403
FaultCode: Client.InvalidInput → 400
FaultCode: Server.* → 500 (loglanır, client’a generic mesaj gider)

Her yeni FaultCode çıktığında mapping’i güncellemek gerekiyor.

Versiyonlama stratejisi

Migration sırasında iki dünya paralel yaşıyor. Versioning şart:

SOAP endpoint: https://api.example.com/soap/v1
REST endpoint: https://api.example.com/rest/v1

REST v1 SOAP v1’in direct mapping’i olabilir. REST v2’de daha temiz API tasarlayabilirsiniz (endpoint isimleri REST convention’ına göre). Migration tamamlanınca REST v1 deprecate edilir.

Consumer koordinasyonu

SOAP consumer’ların kimler olduğunu bilin. Hangi ekip, hangi sistem, hangi frekansta çağırıyor. Migration planını her consumer ile paralel yürütün.

Deprecation timeline. SOAP endpoint’i kapatma tarihi 6-12 ay önce duyurulmalı. İlk 3 ay response header’a warning ekliyorduk: X-Deprecated: This endpoint will be removed on YYYY-MM-DD. Bazı consumer’lar bu header’ı gördükten sonra bile iletişim gelmedikçe hareket etmiyor.

Access log’ları sürekli izleyin. Son 30 günde SOAP endpoint’i kimler çağırdı? Beklenmeyen IP’ler çıkabilir, offboard’lanmış partnerlar, terk edilmiş iç sistemler.

Cutover günü yaklaşırken 410 Gone dönmeye başlayın, sonra 503 Service Unavailable, en son 404. Aşamalı kapama consumer’ın farketmesini sağlıyor. Sert kapama destek ticket’larını patlıyor.

Testing: contract test şart

Eski SOAP’un davranışını koruyacak REST endpoint yazdığınızda her request type için contract test yazın. SOAP response ile REST response’un semantik olarak eş olduğu doğrulanır.

Pact framework gibi consumer-driven contract test araçları işe yarıyor. Her client ekibi kendi expectation’larını yazıyor, gateway her versiyonda bu contract’lere uygunluğu otomatik doğruluyor.

Performans bonusu

SOAP’tan REST’e geçişin beklemediğimiz bir kazanımı performans oldu. XML parse etmek JSON’dan 3-5 kat yavaş, envelope overhead’i %30 daha fazla byte demek, gzip compression JSON’da daha iyi çalışıyor. Migration sonrası p95 latency %25-40 iyileşti.

Son öğüt

SOAP’tan REST migration mühendislik problemi olmaktan çok organizasyonel problem. Protocol translation kodu bir haftada yazılır, ama 30 consumer’ı koordine etmek, kimlik doğrulama, monitoring, regresyon takibi aylar alır.

Başlangıçta zaman tahminini 3’e çarpın. 3 projede de 6 aylık tahminler 18 ayda tamamlandı.

SOAP’tan REST’e migration: 18 ayda yaptığım 3 proje