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 (Authorization: Bearer mck_…); misafir projeler: paylaşım token'ı

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

Hesabındaki bir projenin mock runtime API'sine yapılan her istek bir API key taşır. Geçerli bir key içermeyen istekler, projenin önizleme paylaşım ayarı ne olursa olsun reddedilir — paylaşım bağlantısı API'yi değil, önizleme sayfasını açar.

API Key'ler

Key'leri uygulamada Hesap → API anahtarları altında, aktif proje için oluşturursun. API key'ler Professional planından itibaren dahildir. Her key:

• Tek bir projeye aittir ve yalnızca o proje için yanıt verir
• Yalnızca bir kez, oluşturulduğunda tam olarak gösterilir — onu bir parola gibi sakla
• Bir son kullanma tarihi taşıyabilir ve istendiği zaman iptal edilebilir
• Bir kapsamı vardır: Runtime mock verileri sorgular, Full ayrıca yönetim API'sine erişir; Management key runtime'ı sorgulayamaz

Key'i bearer token olarak gönder:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

X-API-Key: mck_your_api_key başlığı da çalışır.

Key'i tarayıcı kodunun dışında tut

API key bir sırdır. Mock API'yi sunucu tarafı koddan, CI'dan veya başlığı ekleyen bir geliştirme sunucusu proxy'si üzerinden çağır (aşağıdaki entegrasyon akışının 4. adımı) — key'i asla bir frontend bundle'ı içinde dağıtma.

Misafir Projeler

Misafir bir projenin (hesapsız) API key'i yoktur. Endpoint'i, projenin paylaşım token'ını — önizleme paylaşım bağlantısındaki token'ı — sorgu parametresi olarak kabul eder:

curl -X POST "https://api.mockomat.com/mock/my-guest-project/graphql?token=<share-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name } total } }"}'

Misafir istekleri, misafir oturumunun günlük istek kotasından düşülür.

Actor Token'ları (İsteğe Bağlı)

Actor token'ları aynı API key'in tüketicilerini birbirinden ayırır; böylece bir key'in eş zamanlı kullanımı sınırlanabilir. İsteğe bağlıdırlar — yalnızca API key içeren bir istek de yanıtlanır.

1. Token talep et — API key'inle:

curl -X POST https://api.mockomat.com/runtime/actors \
  -H "Authorization: Bearer mck_your_api_key"

Yanıt:

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

2. Token'ı gönder — runtime isteklerinle birlikte:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "X-Actor-Token: act_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

3. Boşta kalma süresi — bir token, istek gelmeyen 15 dakikanın ardından sona erer; her istek süreyi uzatır. Bir key'in tüm actor yuvaları doluyken yeni bir actor, Retry-After başlığıyla birlikte 429 MAX_ACTIVE_ACTORS_REACHED alır.

int-01-authenticationMissing

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

Sorgu Kalıpları

Temel Liste Sorgusu

query {
  products(page: 1, pageSize: 20) {
    items {
      id
      name
      price
      category {
        id
        name
      }
    }
    total
    page
    pageSize
  }
}

Detay Sorgusu

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

Filtreli Sorgu

Argümanlar, operasyonun API tasarımında tanımladığı parametrelerdir (burada price üzerinde gte ile minPrice, eq ile category); operatörler, arama ve sayfalandırma için Runtime sayfasına bak.

query {
  products(minPrice: 10, category: "electronics", pageSize: 50) {
    items {
      id
      name
      price
    }
    total
  }
}

Sıralanmış ve Sayfalanmış Sorgu

query {
  products(sortField: "price", sortDirection: ASC, page: 2, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
    page
    pageSize
  }
}

İç İçe İlişki Sorgusu

query {
  customers(pageSize: 10) {
    items {
      id
      firstName
      lastName
      orders {
        id
        totalAmount
        createdAt
      }
    }
    total
  }
}

Ö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

Test paketini, backend-for-frontend'ini veya diğer tüketicileri mock endpoint'e bağla. Endpoint'i ve API key'i yapılandırmada tut; böylece Mockomat ile gerçek backend'in arasında geçiş yapabilirsin.

Bir frontend uygulaması mock API'ye, key'i sunucu tarafında ekleyen geliştirme sunucusunun proxy'si üzerinden ulaşır — böylece key asla bundle'a girmez:

// vite.config.ts — /mock-api'yi Mockomat'a yönlendirir ve API key'i ekler
export default defineConfig({
  server: {
    proxy: {
      '/mock-api': {
        target: 'https://api.mockomat.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/mock-api/, '/mock/my-project'),
        headers: { Authorization: `Bearer ${process.env.MOCKOMAT_API_KEY}` },
      },
    },
  },
});

// environment.ts — uygulama yalnızca proxy yolunu bilir
export const environment = {
  apiUrl: '/mock-api/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: Smoke-check the mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: |
      # 401/403/404'te adımı başarısız kılar: eksik, iptal edilmiş veya başka projeye ait key
      curl -sf "$API_URL" \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"query":"{ products(page: 1, pageSize: 1) { items { id } total } }"}'

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ı

Mock runtime API için üç sınır geçerlidir:

Kapsam	Sınır	Ulaşıldığında
IP adresi başına	Dakikada 60 istek	429 TOO_MANY_REQUESTS — bir dakika sonra yeniden dene
Hesap başına	Planının istek kotası (günlük veya aylık)	Kota sıfırlanana kadar 429 TOO_MANY_REQUESTS
API key başına	Eş zamanlı actor'lar — yalnızca actor token'ı gönderiyorsan	Retry-After başlığıyla 429 MAX_ACTIVE_ACTORS_REACHED

Misafir projeler, misafir oturumunun günlük kotasından düşülür.

Hata Yönetimi

Reddedilen bir istek, bir HTTP hata durumu ve bir JSON gövdesiyle yanıt verir. Kararını gövdedeki code alanına göre ver:

HTTP Durum	Kod	Anlam	Eylem
400	Bad Request	Geçersiz GraphQL, bilinmeyen veya devre dışı operasyon, hatalı gövde	message alanını oku; sorguyu veya operasyon adını düzelt
401	UNAUTHENTICATED	API key gönderilmedi (misafir proje: paylaşım token'ı eksik veya yanlış)	Authorization: Bearer mck_… gönder
401	API_KEY_INVALID	Bilinmeyen, iptal edilmiş veya silinmiş key	Yeni bir key oluştur
401	API_KEY_EXPIRED	Key'in son kullanma tarihi geçti	Yeni bir key oluştur
401	ACTOR_TOKEN_INVALID	Hatalı biçimli X-Actor-Token	/runtime/actors üzerinden token al veya başlığı gönderme
403	API_KEY_SCOPE_INSUFFICIENT	Yalnızca yönetim kapsamlı key	Runtime veya Full key kullan
404	PROJECT_NOT_FOUND	Bilinmeyen slug veya key'in ait olmadığı bir proje (/runtime/actors için: key'in projesi silinmiş)	Slug'ı kontrol et; bu projenin key'ini kullan
429	TOO_MANY_REQUESTS	IP başına sınıra veya plan kotasına ulaşıldı	Bekle, sonra yeniden dene
429	MAX_ACTIVE_ACTORS_REACHED	Key'in tüm actor yuvaları dolu	Retry-After süresini bekle
429	RATE_LIMIT_EXCEEDED	Bir key için çok fazla actor token isteği (POST /runtime/actors)	Retry-After süresini bekle; etkin bir token'ı yeniden kullan
503	QUERY_TIMEOUT	Sorgu çok uzun sürdü	Yeniden dene; sorguyu daralt

Hata Yanıt Formatı

{
  "statusCode": 401,
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID",
  "path": "/mock/my-project/graphql",
  "timestamp": "2026-10-05T09:30:00.000Z"
}

Retry-After başlığı taşıyan bir 429, gövdede ayrıca retryAfter (saniye) içerir. Yanıtlanan bir istek, GraphQL gövdesiyle 200 döndürür; veri düzeyindeki sorunlar errors[] içinde gelir — örneğin extensions.code NOT_READY, tablonun henüz veriye bağlanmadığı anlamına gelir.

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.