Entegratörler

Bu bölüm, Mockomat iş akışlarını daha geniş mühendislik sistemlerine bağlayan geliştiriciler içindir. Bir Mockomat mock API'sini tüketen bir frontend oluşturuyor ol, CI/CD'de model doğrulamasını otomatikleştiriyor ol veya Mockomat'ı takımının geliştirme pipeline'ına entegre ediyor ol, bu sayfa ihtiyacın olan kalıpları ve uygulamaları kapsar.

API Endpoint'lerine Genel Bakış

Mockomat iki farklı API yüzeyi sunar:

API	Endpoint	Amaç	Kimlik Doğrulama
Management API	GET /graphql	Proje CRUD, model yapılandırması, kullanıcı yönetimi	JWT (oturum tabanlı)
Mock Runtime API	POST /mock/{slug}/graphql	Mock veri sorgulama, alan davranışı testi	API key + Actor Token (Business+) veya public (Free/Quick)

Management API, Mockomat web uygulaması ve yönetim araçları tarafından kullanılır. Mock runtime API, uygulamalarının mock backend olarak tükettiğidir.

Kimlik Doğrulama Kalıpları

Kimlik doğrulama gereksinimleri planına ve endpoint türüne bağlıdır.

Public Endpoint'ler (Quick ve Free)

Public endpoint'ler kimlik doğrulama gerektirmez. Herhangi bir HTTP istemcisi sorgu gönderebilir:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(limit: 10) { id name price } }"}'

Public endpoint'ler, kötüye kullanımı önlemek için IP adresi başına hız sınırlıdır.

Private Endpoint'ler (Business ve Enterprise)

Private endpoint'ler iki kimlik doğrulama başlığı gerektirir:

Başlık	Değer	Amaç
Authorization	Bearer <API_KEY>	Projeyi tanımlar ve erişimi yetkilendirir
X-Actor-Token	<ACTOR_TOKEN>	Eş zamanlılık takibi için tüketiciyi tanımlar

API Key Kimlik Doğrulaması

API key'ler Mockomat workspace'inde proje başına oluşturulur. Her key:

• Tek bir projeye kapsamlıdır
• Diğer key'leri etkilemeden döndürülebilir
• Kendi eş zamanlılık ve hız limitlerine sahiptir
• Herhangi bir zamanda iptal edilebilir

Actor Token İş Akışı

Actor token'ları eş zamanlı API tüketicilerini yönetir. İş akışı:

1. Token talebinde bulunun — API key'in ile actor endpoint'ini çağır:

curl -X POST https://api.mockomat.com/runtime/actors \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json"

Yanıt:

{
  "actorToken": "act_abc123...",
  "expiresInSeconds": 900,
  "maxActors": 5,
  "currentActors": 2
}

2. Token'ı kullan — sonraki tüm runtime isteklerine dahil et:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Actor-Token: act_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(limit: 10) { id name price } }"}'

3. Token süresi dolar — actor token'ları yapılandırılabilir bir boşta kalma zaman aşımına sahiptir (varsayılan 15 dakika). Her istek zaman aşımını yeniler. Token'ın süresi dolarsa, yeni bir tane talep et.

int-01-authenticationMissing

Kimlik doğrulama ve bağlam kurulumu ile entegrasyon girişi.

Sorgu Kalıpları

Temel Liste Sorgusu

query {
  products(offset: 0, limit: 20) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

Detay Sorgusu

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Filtreli Sorgu

query {
  products(
    filter: {
      filterGroup: {
        operator: AND
        items: [
          { attribute: "price", operator: GE, value: "10" }
          { attribute: "category", operator: EQ, value: "electronics" }
        ]
      }
    }
    limit: 50
  ) {
    id
    name
    price
  }
}

Sıralanmış ve Sayfalanmış Sorgu

query {
  products(
    sort: { field: "price", direction: ASC }
    offset: 20
    limit: 20
  ) {
    id
    name
    price
  }
}

İç İçe İlişki Sorgusu

query {
  customers(limit: 10) {
    id
    firstName
    lastName
    orders {
      id
      totalAmount
      createdAt
      items {
        id
        productName
        quantity
        unitPrice
      }
    }
  }
}

Önerilen Entegrasyon Akışı

1. Kararlı Bir Alan Kapsamı Tanımla

Entegre etmeden önce, uygulamanın hangi varlıkları ve sorguları tüketeceğini belirle. Hâlâ sık değişen bir modele karşı entegre etme — temel yapı kararlı olana kadar bekle.

2. Adlandırma ve Alan Sözleşmelerini Kilitle

GraphQL şemasını bir sözleşme olarak değerlendir. Uygulaman belirli sorgu adlarına ve alan yapılarına bağımlı olduğundan, bu adlardaki değişiklikler entegrasyonu bozar. Tüketicileri bağlamadan önce sorgu adlarını kesinleştirmek için Mockomat'taki API design görünümünü kullan.

3. Runtime Davranışını Doğrula

Runtime önizlemesi aracılığıyla kapsamlı sorgular çalıştır ve doğrula:

• Alan tipleri uygulamanın beklentileriyle eşleşiyor
• İlişki iç içe geçmesi doğru çalışıyor
• Filtreler beklenen alt kümeleri döndürüyor
• Sayfalama temiz sayfa sınırları üretiyor

4. Tüketici Sistemlerini Entegre Et

Frontend uygulamanı, test paketini veya diğer tüketicileri mock endpoint'e bağla. Mockomat endpoint'leri ile gerçek backend'ler arasında geçiş yapmak için ortam değişkenleri veya yapılandırma dosyaları kullan:

// environment.ts
export const environment = {
  apiUrl: 'https://api.mockomat.com/mock/my-project/graphql',
  // Hazır olduğunuzda gerçek backend'e geçin:
  // apiUrl: 'https://api.myapp.com/graphql',
};

5. Dışa Aktarım/Uygulamaya Terfi Et

Mock API sözleşmesi kararlı olduğunda ve frontend'in buna karşı doğru çalıştığında, aynı sözleşmeyi uygulayan bir üretim backend'i oluşturmak için Dışa Aktarım özelliğini kullan.

int-02-ci-cd-flowMissing

Model ve runtime geçitleriyle CI/CD entegrasyon kalıpları.

CI/CD ve Otomasyon

Mockomat mock API'leri, kararlı bir mock backend'e karşı frontend davranışını doğrulamak için CI/CD pipeline'ına entegre edilebilir.

Pipeline Entegrasyon Kalıpları

Sözleşme doğrulaması — model değişikliklerinde şema karşılaştırma kontrolleri çalıştırarak tüketicilere ulaşmadan önce kırılıcı değişiklikleri tespit et.

Entegrasyon testleri — gerçekçi mock verilerine karşı frontend davranışını doğrulamak için entegrasyon test paketini Mockomat endpoint'ine yönlendir.

Önizleme doğrulaması — model değişikliklerini birleştirmeden önce, önizleme endpoint'ini programatik olarak sorgulayarak runtime'ın beklenen sonuçları ürettiğini doğrula.

Örnek Pipeline Adımları

# Örnek CI pipeline adımı
steps:
  - name: Run integration tests against mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: npm run test:integration

  - name: Validate schema contract
    run: |
      # Mevcut şemayı getirin ve referansla karşılaştırın
      curl -s $API_URL -d '{"query":"{ __schema { types { name } } }"}' \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" > current-schema.json
      diff baseline-schema.json current-schema.json

Oluşturulan Yapıların Sürümlenmesi

Dışa aktarım özelliğini kullanırken, oluşturulan backend kodunu uygulamanla birlikte sürümle:

• Oluşturulan kodu özel bir dal veya depoya kaydet.
• Dışa aktarımları model sürümü veya tarih ile etiketle.
• Son dışa aktarımdan bu yana model değişikliklerini özetleyen bir değişiklik günlüğü ekle.
• Oluşturulan kod farklarını ana dala birleştirmeden önce incele.

Hız Sınırlaması

Mockomat, adil kullanım ve platform kararlılığı sağlamak için birden fazla seviyede hız sınırlaması uygular.

Kapsam	Free/Quick	Business	Enterprise
IP başına	60 istek/dk	Yok	Yok
API key başına	Yok	Plana göre	Özel
Tenant başına	Yok	Yok	Yapılandırılabilir

Hız sınırlandığında, API yeniden denemeden önce ne kadar beklemen gerektiğini belirten bir Retry-After başlığıyla HTTP 429 (Too Many Requests) yanıtı döndürür.

Hata Yönetimi

Yaygın hata yanıtları ve bunların nasıl ele alınacağı:

HTTP Durum	Hata Kodu	Anlam	Eylem
400	INVALID_QUERY	GraphQL sorgu sözdizimi hatası	Sorgu sözdizimini kontrol et
401	UNAUTHORIZED	Eksik veya geçersiz API key	API key başlığını doğrula
401	SESSION_EXPIRED	Actor token süresi dolmuş	Yeni bir actor token talep et
403	MAX_TENANT_SESSIONS_REACHED	Eş zamanlı oturum limitine ulaşıldı	Bir oturumun süresinin dolmasını bekle veya birini serbest bırak
404	PROJECT_NOT_FOUND	Geçersiz proje slug'ı	Endpoint URL'sini doğrula
429	RATE_LIMITED	Çok fazla istek	Retry-After süresini bekle
429	MAX_ACTIVE_ACTORS_REACHED	Eş zamanlı actor limitine ulaşıldı	Bir actor'un süresinin dolmasını bekle

Hata Yanıt Formatı

{
  "error": "MAX_ACTIVE_ACTORS_REACHED",
  "maxActors": 5,
  "currentActors": 5,
  "retryAfterSeconds": 342
}

Mevcut olduğunda her zaman retryAfterSeconds alanını kontrol et — yeniden denemeden önceki minimum bekleme süresini belirtir.

Gözlemlenebilirlik ve Tanı

Entegrasyon güvenilirliğini sürdürmek için ortamlar genelinde şu temel sinyalleri takip et:

Temel Metrikler

• Sorgu kararlılığı — yanıtlar tutarlı şekilde yapılandırılmış mı? Beklenmeyen şema değişikliklerine dikkat et.
• Yanıt şekli kayması — model güncellemeleri arasında alan tipleri veya iç içe geçme seviyeleri değişiyor mu?
• İlişki arama güvenilirliği — iç içe sorgular tutarlı şekilde doğru çözümleniyor mu?
• Hata ve zaman aşımı kalıpları — belirli sorgular tutarlı şekilde yavaş mı veya başarısız mı oluyor?
• Hız limiti yakınlığı — istek veya eş zamanlılık limitlerine ne kadar yakınsın?

İzleme Önerileri

• Tüketici uygulamanda tüm API yanıtlarını (veya en azından durum kodlarını ve yanıt sürelerini) kaydet.
• HTTP 429 ve 401 yanıtları için uyarılar ayarla — bunlar yapılandırma veya kapasite sorunlarını gösterir.
• İstenmeyen kaymayı tespit etmek için yanıt şemalarını periyodik olarak bir referansla karşılaştır.
• Eş zamanlılık stratejini optimize etmek için actor token yenileme kalıplarını izle.

int-03-observabilityMissing

Entegrasyon güvenilirliği için gözlemlenebilirlik kontrol noktaları.

En iyi uygulama

Developer / Integrator

Mockomat yapılarını sözleşme öncelikli varlıklar olarak değerlendir. Model amacını, runtime davranışını ve uygulama kararlarını aynı değişiklik setinde izlenebilir tut. Frontend'in belirli bir sorgu şekline bağımlıysa, bu bağımlılığı dokümante et ve CI'da doğrula.

Enterprise entegrasyon notu

Enterprise User

Enterprise ortamlar için, ortam başına (geliştirme, staging, üretim) ayrı API key'ler kullan. Bu, ortam başına kullanımı izlemeni ve key'leri bağımsız olarak döndürmeni sağlar. Her ortamın kaç eş zamanlı tüketiciyi desteklediğini tam olarak kontrol etmek için actor token'larla birleştir.