Apidog, birçok formatta API özelliklerini içe aktarmayı destekleyen bir API işbirliği ve yönetim platformudur. OpenAPI/Swagger, Postman Collections, HAR dosyaları ve cURL komutları dahil olmak üzere neredeyse tüm ana akım API özellik formatlarını doğrudan içe aktarabilir.
Ancak, birçok gerçek projede asıl zorluk API özelliklerini nasıl içe aktaracağınız değil, en başta içe aktarılacak API özelliklerinin olmamasıdır. Bazı eski veya miras kalan sistemler hiçbir zaman API dokümantasyonu tutmamış ve OpenAPI veya Swagger dosyalarına sahip değildir.
Bu durumlarda, eksik API dokümantasyonunu hızlı bir şekilde yeniden oluşturmanız veya test uzmanlarının gerçek verilerle çalışabilmesi için test senaryoları oluşturmanız gerekiyorsa, paket yakalama aracı kullanmak genellikle en hızlı yaklaşımdır.
Uygulamanın HTTP/HTTPS trafiğini yakalayarak, faydalı istekleri filtreleyerek, bunları HAR veya cURL olarak dışa aktararak ve ardından Apidog'a aktararak, hızlı bir şekilde API dokümantasyonu oluşturabilir ve daha fazla API testi için zemin hazırlayabilirsiniz.
Trafik kaydı için birçok araç mevcuttur. Bu makale, ilgili özel işlemleri göstermek için Charles Proxy'yi örnek olarak kullanmaktadır, ancak Proxyman, Fiddler veya tarayıcınızda yerleşik geliştirici araçları gibi alternatifleri de paket yakalama için kullanabilirsiniz. Çekirdek iş akışı bu araçlarda temelde aynıdır.
Charles Kurulumu ve Temel Yapılandırma
Charles 30 günlük ücretsiz deneme sunar. En son sürümü resmi web sitesinden indirebilir ve sisteminize kurabilirsiniz.
Charles'ı ilk başlattığınızda, Ağ ayarlarını otomatik olarak yapılandırıp yapılandırmayacağını sorabilir. Gerekli izinleri vermek için "Ayrıcalık Tanı" seçeneğini seçmeniz önerilir. Bu, Charles'ın sisteminizden HTTP trafiğini otomatik olarak yakalamasına olanak tanır.
HTTPS Yakalama İçin Charles Kök Sertifikasını Yükleme
HTTPS trafiğini yakalamak için Charles'ın kök sertifikasını yüklemeniz gerekir. Bu adım çok önemlidir çünkü çoğu modern API HTTPS kullanır.
macOS'te:
- Menü çubuğundan "Yardım → SSL Proxying → Charles Kök Sertifikasını Kur" seçeneğine tıklayın
- Anahtar Zinciri Erişimi uygulaması otomatik olarak açılacaktır
- Charles Proxy sertifikasını arayın ve bulun
- Çift tıklayın ve güven ayarını "Her Zaman Güven" olarak değiştirin
Windows'ta:
- Menü çubuğundan "Yardım → SSL Proxying → Charles Kök Sertifikasını Kur" seçeneğine tıklayın
- Kurulum işlemi sırasında sertifikayı "Güvenilen Kök Sertifika Yetkilileri" deposuna yükleyin
SSL Proxy'yi Etkinleştirme
Sertifika yüklendikten sonra, SSL proxy'yi etkinleştirmeniz gerekir:
- Charles menü çubuğundan Proxy → SSL Proxying Settings öğesini seçin
- "Enable SSL Proxying" seçeneğini işaretleyin
3. Yakalamak istediğiniz alan adlarını (Host) ve bağlantı noktalarını (Port 443) listeye ekleyin
4. Tüm alan adlarını izlemek için * karakterini de kullanabilirsiniz
Yapılandırma tamamlandıktan sonra, Charles tam HTTP/HTTPS isteklerini ve yanıtlarını yakalayabilir.
İpucu: Uygulamanızın hangi alan adlarını kullandığından emin değilseniz, önce uygulamayı serbestçe çalıştırabilir ve ardından Charles oturum listesindeki "Şifreli" altındaki istekleri gözlemleyebilirsiniz. İlgili alan adlarını not alın ve ardından bunları Charles'ın SSL Proxying ayarlarına ekleyin.
Uygulamanızdan API Trafiğini Kaydetme
Analiz etmek istediğiniz uygulamayı veya web sayfasını başlatın ve giriş yapma, veri sorgulama, form gönderme veya dosya yükleme gibi çeşitli özelliklerle etkileşim kurun. Charles'ın sol tarafındaki oturum ağacı, istekleri alan adına ve URL'ye göre gruplandırarak gerçek zamanlı olarak güncellenecektir.
Belirli bir isteği seçtiğinizde, sağ panel o isteğin temel bilgilerini ve yanıt içeriğini görüntüler. İçerikler sekmesinde, JSON ve diğer yanıtlar ağaç yapısı halinde daraltılır, bu da veri yapısını ve alanlarını hızlı bir şekilde anlamayı kolaylaştırır.
API Uç Noktalarını Filtreleme ve Dışa Aktarma
Kaydetme tamamlandıktan sonra, çok sayıda isteğin yakalandığını görebilirsiniz. Gerçek API çağrılarının yanı sıra, çeşitli statik kaynak istekleri, üçüncü taraf hizmet çağrıları ve diğer ağ trafiği bulunmaktadır. Bu noktada, yalnızca ilgilendiğiniz uç noktaları filtrelemeniz ve saklamanız gerekir.
Filtreleme Seçenekleri
1. Belirli alan adlarına veya yollara odaklanma:
Bir alan adına veya yola sağ tıklayın ve "Odaklan"ı seçin
Charles, yalnızca o düğüm altındaki istekleri tutarak analizinizi kolaylaştırır
2. İlgisiz istekleri kaldırma:
İlgisiz isteklere sağ tıklayın ve bunları kaldırmak için "Temizle"yi seçin
Veya birden çok isteği seçin ve bunları toplu olarak silin
3. Önbellekleme sorunlarını ele alma:
Önbellekleme, HTML veya JSON'un doğru görüntülenmemesine neden oluyorsa, sağ tıklayın ve "Önbelleksiz"i seçin
Bu, Charles'ın sonraki isteklerde önbelleklemeyi göz ardı etmesine neden olarak tam yanıt içeriğini yakalamanıza olanak tanır
HAR Dosyası Olarak Dışa Aktarma
Filtreleme tamamlandıktan sonra, seçtiğiniz oturumları dışa aktarın:
- Dışa aktarmak istediğiniz oturumları seçin:
Tüm bir alan adını seçebilir veya
Cmd (Mac) veya Ctrl (Windows) tuşuna basılı tutarak belirli istekleri tek tek seçebilirsiniz
Menü çubuğundan Dosya → Oturumu Dışa Aktar'ı seçin
Dışa aktarma iletişim kutusunda, bir HAR dosyası oluşturmak için "HTTP Archive (.har)" formatında dışa aktarmayı seçin
API Dokümantasyonunu Otomatik Oluşturmak İçin Apidog'a İçe Aktarma
Şimdi yakaladığınız trafiği Apidog'a aktarma zamanı:
- Apidog istemcisini açın
2. Proje Ayarları → Veri İçe Aktar → .har Dosyası'na gidin
3. Charles'tan dışa aktardığınız HAR dosyasını seçin
Apidog, dosya içeriğini otomatik olarak ayrıştıracak ve algılanan uç nokta bilgilerini önizleme alanında görüntüleyecektir:
- Algılanan uç nokta sayısı
- İstek yöntemleri (GET, POST, PUT, DELETE vb.)
İçe aktarma işlemi sırasında aşağıdaki gibi seçenekleri yapılandırabilirsiniz:
- Hangi modüle içe aktarılacağı
- Mevcut uç noktaların üzerine yazılıp yazılmayacağı
İçe aktarma tamamlandıktan sonra, uç noktaları ilgili modülde görüntüleyebilirsiniz.
API Dokümantasyonunu İyileştirme ve Optimize Etme
Otomatik oluşturulan API dokümantasyonu harika bir başlangıç noktasıdır, ancak genellikle iş gereksinimlerinizi karşılamak için daha fazla ayarlama gerektirir. İşte bazı yaygın iyileştirmeler:
- Uç nokta adlarını iyileştirme: Genel adları daha açıklayıcı olanlarla değiştirin
- Parametre açıklamaları ekleme: Her bir parametrenin ne işe yaradığını ve ne zaman kullanılacağını belgeleyin
- Yanıt bileşenlerini iyileştirme: Yanıt bileşenlerini iş mantığınıza uyacak şekilde düzenleyin
- Örnekler ekleme: Örnek istekler ve yanıtlar ekleyin
- Kimlik doğrulamayı yapılandırma: Bir uç nokta kimlik doğrulama gerektiriyorsa, Apidog'un ortam değişkenlerinde veya Kimlik Doğrulama ayarlarında ilgili bilgileri yapılandırın. Bu, test yaparken API çağrılarınızın doğru çalışmasını sağlar.
Son Not
Paket yakalama araçlarını kullanarak HTTP/HTTPS trafiğini kaydedip ardından Apidog'a aktararak, hızlı bir şekilde API dokümantasyonu oluşturabilir ve test için gerçek veri desteği sağlayabilirsiniz.
İster bir tarayıcı, ister masaüstü istemcisi veya mobil uygulama olsun, bu yöntem API dokümantasyonu hazırlığı için harcanan zamanı önemli ölçüde azaltabilir ve ekibinizin API testi ve geliştirmeye hızlı bir şekilde başlamasını sağlayabilir.