Ortak Veri Modeli

Ortak Veri Modeli Kavramı

Ortak Veri Modeli, API Designer'ın spec first yaklaşımında yeniden kullanılabilir şema tanımları oluşturmanıza olanak sağlar. Mesaj içeriğindeki veri tiplerini tanımlayan ortak şema modelleri oluşturarak, model kalıtımı ve paylaşılan bileşenler ile JSON Schema referansları kullanabilirsiniz. Oluşturulan modeller Spec Tasarım Editörü içerisinde içe aktarılarak kullanılabilir.

Yeniden Kullanılabilir Şemalar

Ortak şema modelleri oluşturulur

Aynı veri yapısı birden çok API'de kullanılabilir.

Model Kalıtımı

Model kalıtımı ve referanslar

JSON Schema referansları ile model ilişkileri.

Paylaşılan Bileşenler

Paylaşılan bileşenler kullanılır

Ortak veri tipleri merkezi olarak yönetilir.

Spec Tasarım Editörü Entegrasyonu

Spec Tasarım Editörü'nde kullanım

Oluşturulan modeller API Spec'lerde içe aktarılabilir.

Ortak Veri Modeli Özellikleri

Şema Tasarımı

Ortak veri modellerinde şema tasarımı ve özellik yönetimi:

Veri Tipi Tanımları

• Temel veri tipleri (string, integer, number, boolean)
• Karmaşık veri tipleri (object, array)
• Enum değerleri
• Format tanımlamaları

Şema Özellikleri

• Property tanımları
• Zorunlu alanlar
• Read-only ve write-only davranışları
• Validation kuralları

Model Referansları

• $ref ile model referansları
• Model kalıtımı
• Paylaşılan bileşenler
• JSON Schema referansları

Veri Modeli Yönetimi

Ortak veri modellerinin oluşturulması ve yönetimi:

Model Oluşturma

Yeni ortak veri modelleri oluşturulur

• Ad ve açıklama tanımlama
• Şema yapısı oluşturma
• Örnek değerler ekleme

Şema Özellikleri

Şema içerisinde özellikler tanımlanır

• Property ekleme ve düzenleme
• Tip ve format belirleme
• Validation kuralları

Model İçe Aktarma

Modeller Spec Tasarım Editörü'nde kullanılır

• Spec içerisinde model referansı
• Paylaşılan bileşen kullanımı
• Yeniden kullanılabilirlik

Ortak Veri Modeli Oluşturma

Liste arayüzünün sağ üst kısmındaki Yeni (Create) butonuna tıklanarak yeni bir Veri Modeli oluşturulabilir.

Ortak Veri Modeli oluşturma ayarları aşağıdaki görselde gösterilmektedir:

Ortak veri modeli oluşturma konfigürasyonu için kullanılan alanlar aşağıdaki tabloda görülmektedir.

Alan	Açıklama
Ad	Veri modelinin ad bilgisidir.
Açıklama	Veri modeline ilişkin açıklamadır.
Şema (Schema)	Veride yer bulunacak özellikler ve alanların tipi, pattern, min-max gibi özellikleri yönetilir.
Örnek (Example)	Veri tipinin bir örneği oluşturabilir.

Şema Özelliği Ekleme

Şema içerisinde özellikler (properties) ekleyerek veri modelinizin yapısını tanımlayabilirsiniz.

Şema Özelliği ekleme ayarları aşağıdaki görselde gösterilmektedir:

Şema Özelliği oluşturma konfigürasyonu için kullanılan alanlar aşağıdaki tabloda görülmektedir.

Alan	Açıklama
Ad	Şemanın ad bilgisidir.
Açıklama	Şema hakkında açıklama yapılabilir.
Tip	Şemanın tipinin belirtildiği alandır.
Format (Format)	Seçilen tipe göre aktif olan bir alandır. Bazı tipler için seçilebilecek formatlar bulunur: integer - int32: İşaretli 32 bit tam sayılar (yaygın olarak kullanılan tam sayı türü). - int64: İşaretli 64 bit tam sayılar (uzun tip). number - float: Ondalıklı sayılar (6 basamak). - double: Ondalıklı sayılar (14 basamak). string - byte: Base64 ile kodlanmış karakterler. Örneğin, U3dhZ2dlciByb2Nrcw== - binary: Dosyaları tanımlamak için kullanılan ikili veri - date: Tam tarih gösterimi. Örneğin, 2017-07-21 - date-time: Tarih-saat gösterimi. Örneğin, 2017-07-21T17:32:28Z - password: Girişi maskelemek için kullanılır.
$Ref Target	Eğer tip alanından $ref seçilirse bu alan aktifleşir. Başka bir veri modelinin referansı verilebilir.
Özellik (Property is)	Modelin kullanımının zorunlu olup olmadığı belirtilir.
Davranım (Behaviour)	Şemanın yalnızca okunur/yazılır (Read Only, Write Only) bilgisi belirlenir.
Integer Özellikleri (Integer Properties)	Tip olarak Integer seçilmiş ise bu alanlar aktif olur: - Minimum: Girilebilecek değerlerin en küçüğünü belirlemek içindir. - Maximum: Girilebilecek değerlerin en büyüğünü belirlemek içindir. - MultipleOf: Girilecek değerlerin bir sayının katı olması isteniyorsa bunu belirlemek içindir.
String Özellikleri (String Properties)	Tip olarak String seçilmiş ise bu alanlar aktif olur: - Desen (Pattern): String değeri için bir normal ifade şablonu tanımlamanıza olanak tanır. Yalnızca bu şablonla eşleşen değerler kabul edilecektir. - Minimum Uzunluğu (Min Length): Girilebilecek değerlerin minimum uzunluğunu belirlemek içindir. - Maksimum Uzunluğu (Max Length): Girilebilecek değerlerin maksimum uzunluğunu belirlemek içindir.
Enum Değerleri (Enum Values)	Tip olarak Enum seçilmiş ise bu alan aktif olur. Modelin olası değerlerininin girildiği alandır.
Örnek (Example)	Şemayı tarif eden bir örnek verilebilir.

Ortak Veri Modeli Kullanım Senaryoları

Spec first yaklaşımında ortak veri modellerinin kullanım senaryoları:

Yeniden Kullanılabilir Şema Oluşturma

1. Ortak veri modeli oluşturma
2. Şema özelliklerini tanımlama
3. Modeli Spec Tasarım Editörü'nde içe aktarma
4. Birden çok API Spec'te kullanma
5. Merkezi güncelleme ve yönetim

Model Kalıtımı ve Referanslar

1. Temel veri modelleri oluşturma
2. Model referansları ile ilişkiler kurma
3. $ref ile model kalıtımı
4. Paylaşılan bileşenler kullanma
5. Tutarlı veri yapıları

Ortak Veri Modeli ve Spec Tasarım Editörü İlişkisi

Ortak Veri Modelleri, Spec Tasarım Editörü ile entegre çalışır. İşleyiş akışı:

Ortak Veri Modelleri
   │
   │ Şema Tanımları
   │ Model Referansları
   │
   ▼
Spec Tasarım Editörü
   │
   │ Model İçe Aktarma
   │ $ref Referansları
   │
   ▼
API Spec
   │
   │ Paylaşılan Bileşenler
   │
   ▼
API Proxy

1. Model Oluşturma

Ortak Veri Modelleri sayfasında model oluşturulur

Şema özellikleri ve yapısı tanımlanır.

2. Model Tanımlama

Şema özellikleri ve validation kuralları belirlenir

Property'ler, tipler ve formatlar tanımlanır.

3. Spec'te Kullanım

Spec Tasarım Editörü'nde model içe aktarılır

$ref referansları ile model kullanılır.

4. Yeniden Kullanım

Model birden çok API Spec'te kullanılabilir

Merkezi yönetim ve tutarlılık sağlanır.

bilgi

Ortak Veri Modelleri ve Spec Tasarım Editörü arasındaki bu entegrasyon, spec first yaklaşımında yeniden kullanılabilir şema tanımları ile tutarlı ve merkezi yönetilen veri yapıları oluşturmanıza olanak sağlar. Modeller bir kez oluşturulur ve birden çok API Spec'te kullanılabilir.

Ortak Veri Modeli Avantajları

Yeniden kullanılabilir şema tanımlarının sağladığı avantajlar:

Yeniden Kullanılabilirlik

• Aynı şema birden çok API'de kullanılır
• Merkezi şema yönetimi
• Tutarlı veri yapıları

Model Kalıtımı

• $ref ile model referansları
• Model ilişkileri ve kalıtım
• Paylaşılan bileşenler

Merkezi Yönetim

• Tek yerden şema güncelleme
• Değişikliklerin tüm API'lere yansıması
• Versiyon kontrolü

Standart Uyumluluk

• JSON Schema standartlarına uyum
• OpenAPI/Swagger uyumluluğu
• Tool desteği

Sonraki Adımlar

Spec Tasarım Editörü

Spec Tasarım Editörü detayları

API Proxy Oluşturma

API Proxy oluşturma

JSON Schema Validation

JSON şema doğrulama politikası

API Designer

API Designer bileşenini öğrenin