Bir Apidog projesinde, uç noktalar `Modül` → `Klasör` → `Uç Noktalar` şeklinde hiyerarşik bir yapıda yönetilir.
- Modüller, genellikle iş alanı veya hizmete göre gruplandırılmış bağımsız OpenAPI dosyalarını temsil eder.
- Klasörler, bir modül içindeki uç noktaları özellik veya fonksiyona göre düzenler.
- Uç Noktalar, gerçek OpenAPI spesifikasyonları veya API tanımlamalarıdır.
Bu yapıyı anlamak, API'lerinizi verimli bir şekilde düzenlemenin anahtarıdır.
İşte basit bir hiyerarşi örneği:
Apidog Projesi
│
├── Modül: Kullanıcı Hizmeti (iş alanı veya hizmete göre ayrılmış)
│ │
│ ├── Klasör: Kullanıcı Kimlik Doğrulaması (özellik kategorisi)
│ │ │
│ │ ├── Uç Nokta: POST /login (Giriş Yap)
│ │ └── Uç Nokta: POST /register (Kaydol)
│ │
│ └── Klasör: Kullanıcı Bilgileri
│ │
│ └── Uç Nokta: GET /users/{id} (Kullanıcı Bilgilerini Al)
│
└── Modül: Sipariş Hizmeti
│
├── Klasör: Sipariş Yönetimi
│ │
│ ├── Uç Nokta: POST /orders (Sipariş Oluştur)
│ └── Uç Nokta: GET /orders/{id} (Sipariş Detaylarını Al)
│
└── Klasör: Ödeme
│
└── Uç Nokta: POST /payment/submit (Ödeme Gönder)Apidog'da `Modülleri` Anlamak
Proje hiyerarşisini anladıktan sonraki soru şudur: Her projenin modüllere ihtiyacı var mı? Ne zaman yeni bir tane oluşturmalısınız?
Yeni bir proje oluşturduğunuzda, Apidog otomatik olarak varsayılan bir modül oluşturur. Projeniz yalnızca tek bir arka uç hizmeti veya küçük bir uç nokta kümesi içeriyorsa, bu varsayılan modül genellikle yeterlidir. Ancak, birden fazla ayrı API hizmetini yönetmeniz gerekiyorsa, her biri için ayrı bir modül oluşturabilirsiniz.
Örneğin, bir proje arka ucu Kullanıcı, Ürün, Sipariş ve Lojistik gibi hizmetleri içerebilir—her biri belirli bir alandan sorumludur ve genellikle farklı hizmet URL'lerinde dağıtılır. Bu durumda, uç noktalarını bağımsız olarak yönetmek için bu hizmetler için ayrı modüller oluşturulması önerilir.
Klasör ağacının üzerindeki **`+`** düğmesine tıklayarak ve **`Modül`**'ü seçerek bir modül oluşturabilirsiniz.
Oluşturulduktan sonra, sol taraftaki proje ağacında diğerlerinin yanında, klasörler ve uç noktalar için kendi alanıyla görünür. Her modül içinde serbestçe uç noktalar ve klasörler ekleyebilirsiniz.
Modüller birbirinden bağımsızdır; her birinin kendi uç noktaları, şemaları, bileşenleri ve modül değişkenleri bulunur. Ancak, şemalar modüller arasında referans edilebilir. Ayrıca, ortam değişkenleri, veritabanı bağlantıları ve ortak komut dosyaları gibi proje düzeyindeki ayarlar tüm modüller tarafından erişilebilir.
Her modül, eksiksiz bir OpenAPI spesifikasyon dosyasına karşılık gelir. Projenizi dışa aktarırken, OpenAPI dosyaları modül başına oluşturulur.
Bir Modül İçindeki `Klasörleri` Anlamak
Modüllerinizi oluşturduktan sonraki adım, içlerindeki uç noktaları nasıl yapılandıracağınızı planlamaktır.
Her modül, tüm alt klasörleri ve uç noktaları barındıran bir **kök klasör** ile başlar.
Klasörleri doğrudan kök altında oluşturabilir veya diğer mevcut klasörlerin içine yerleştirebilirsiniz.
Klasör yapısını tasarlarken modülün ne kadar karmaşık olduğunu göz önünde bulundurun. Yalnızca birkaç uç noktası olan bir modül için, fonksiyona göre düzenlenmiş basit, tek seviyeli bir klasör genellikle yeterlidir. Ancak daha karmaşık modüller için, her şeyi düzenli ve kolay gezilebilir tutmak amacıyla iyi yapılandırılmış, çok seviyeli klasörler oluşturmak daha iyidir.
Örneğin, bir *Kullanıcı Hizmeti* modülünde, şunlar gibi üst düzey klasörleriniz olabilir:
- Kullanıcı Kimlik Doğrulaması (giriş, kayıt, şifre sıfırlama uç noktaları için)
- Kullanıcı Bilgileri
- Erişim Kontrolü
Bir klasör çok büyür veya mantıksal olarak bağımsız hale gelirse, onu bağımsız bir modüle dönüştürebilirsiniz.
Klasör adının yanındaki `...` simgesine tıklayın ve `...Daha Fazla` > `Yeni Bir Modüle Dönüştür` seçeneğini seçin. Bu, projenizin yapısını ölçeklendikçe iyi düzenlenmiş tutmanıza yardımcı olur.
Bir Modül İçin Ortam Yönetimi ve Yapılandırması
Yapılandırılmış uç noktaların yanı sıra, her modül tipik olarak farklı bir hizmet adresine veya dağıtım ortamına karşılık gelir. Bunları Ortam Yönetimi'nde kolayca yapılandırabilirsiniz.
Ortam yönetimi ayarlarında, her modülün Temel URL'si ayrı ayrı yapılandırılabilir. Örneğin, bir *Test Ortamında*:
- Kullanıcı Hizmeti →
http://user-service:8001 - Sipariş Hizmeti →
http://order-service:8002
Ortamlar arasında geçiş yapıldığında, Apidog her modülün temel URL'sini otomatik olarak günceller. Örneğin, geliştirme ortamından test ortamına geçildiğinde, kullanıcı hizmeti modülünün temel URL'si http://localhost:8001 adresinden http://user-service:8001 adresine, sipariş hizmeti modülünün temel URL'si ise http://localhost:8002 adresinden http://order-service:8002 adresine değişecektir.
Ortam değişkenleri tüm modüller arasında paylaşılır ve ortamlar arasında farklılık gösteren ayarları depolamak için en iyi şekilde çalışır. Buna karşılık, modül değişkenleri her modüle özgüdür — örneğin, kendi API anahtarları veya tokenları — ve o modül içindeki herhangi bir uç noktada kullanılabilir.
Şemaları Yönetme ve Yeniden Kullanma
Verimli şema yönetimi, tekrarlamayı önlemeye yardımcı olur ve modüller arasında tutarlılık sağlar.
Her modülün kendi şema yönetim bölümü vardır; burada iş ile ilgili veri yapılarını tanımlayabilir ve sürdürebilirsiniz. Bu şemalar modül içinde yeniden kullanılabilir veya diğerleri tarafından referans edilebilir.
Örneğin, *Kullanıcı Hizmeti* modülü kullanıcıyla ilgili şemaları tanımlar. *Sipariş Hizmeti* modülü siparişle ilgili şemaları tanımlar. Eğer *Sipariş Hizmeti* kullanıcı bilgilerine referans vermesi gerekiyorsa, *Kullanıcı Hizmeti*'nin şemasını yeniden kullanabilir—yeniden oluşturmaya gerek kalmaz.
Postman'dan Apidog'a: İçe Aktarılan Koleksiyonları ve Uç Noktaları Düzenleme
Ekibiniz daha önce Postman kullandıysa, mevcut koleksiyonları ve uç noktaları Apidog'a kolayca taşıyabilirsiniz.
İçe aktarma sırasında:
- Her bir **Postman Koleksiyonu** bir **Modül** haline gelir.
- Klasör yapıları otomatik olarak eşlenir.
- Uç noktalar ve şemalar korunur.
Bu, Apidog'un modüler sisteminden faydalanırken tanıdık API yapınızı korumanızı sağlar.
Sonuç
Net **modüller** tanımlayarak, **klasörleri** düzenleyerek ve **şemaları** yeniden kullanarak, Apidog projelerinizi düzenli, ölçeklenebilir ve üzerinde iş birliği yapması kolay tutabilirsiniz.
Apidog'un modüler tasarımı, ekiplerin daha hızlı çalışmasına, karışıklığı önlemesine ve karmaşık API'leri tasarımdan dokümantasyona ve test etmeye kadar daha verimli bir şekilde yönetmesine yardımcı olur.