DEV Community

Cover image for Zuplo API'si Nasıl Kullanılır?
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Zuplo API'si Nasıl Kullanılır?

Zuplo hakkında bilgi edindiyseniz ve onunla gerçek bir şeyler göndermek istiyorsanız, bu yazı tam size göre. Platformu öğrenmek hızlıdır, ancak dökümantasyonu farklı kaynaklara yayılmıştır. Bu rehberde, bir projeyi nasıl oluşturacağınız, rota açacağınız, API anahtarı kimlik doğrulaması ve hız limiti ekleyeceğiniz, özel bir TypeScript ilkesi yazacağınız, dağıtıma göndereceğiniz ve Apidog ile test edeceğiniz adım adım gösterilecektir.

Bugün Apidog'u deneyin

Bu sürecin sonunda, kimlik doğrulama, hız limiti, otomatik geliştirici portalı ve CI ile uyumlu bir Git iş akışı ile kaynak API'nızın önünde çalışan bir API gateway’iniz olacak. Tüm işlem yaklaşık otuz dakika sürer.

Zuplo’nun sizin için uygun olup olmadığından emin değilseniz, şu makaleye göz atın: Zuplo API ağ geçidi nedir. Diğer detaylar için Zuplo belgelerine başvurabilirsiniz.

Özet

  • portal.zuplo.com üzerinden kayıt olun veya npm create zuplo ile yerel proje başlatın.
  • config/routes.oas.json dosyasında rotaları tanımlayın ve URL Forward Handler ile kaynak API’ya yönlendirin.
  • Gerekli inbound policy’leri (API anahtarı doğrulama, hız limiti, şema doğrulama) rota dosyası veya Route Designer üzerinden ekleyin.
  • Özel mantık için modules/ klasöründe TypeScript modülleri yazın; runtime üzerinden tip güvenli erişim elde edersiniz.
  • Değişiklikleri bağlı Git dalına gönderin ve bir önizleme ortamı dağıtın; üretime almak için birleştirin.
  • Yayına almadan önce her rotayı Apidog ile test edin.
  • Ücretsiz plan ayda 100K istek sunar, Builder planı aylık 25$’dır.

Ön Koşullar

Başlamadan önce ihtiyacınız olanlar:

  • Bir Zuplo hesabı
  • Gateway’in önünde çalışacak bir kaynak API (yoksa https://echo.zuplo.io kullanılabilir)
  • CLI kullanacaksanız Node.js 18+

Ayrıca yerel geliştirme için bir kod editörü gerekir. VS Code + TypeScript eklentisi önerilir. VS Code içerisinden istek göndermek için Apidog VS Code uzantısını kurabilirsiniz.

Adım 1: Zuplo Projesi Oluşturun

Proje oluşturmanın iki yolu var: Web portali veya CLI.

Seçenek A: Portal Kullanarak

  1. portal.zuplo.com adresinde oturum açın.
  2. "Yeni Proje"ye tıklayın, örneğin acme-gateway adını verin.
  3. "Boş Proje"yi seçin.
  4. Kod sekmesi başlangıç dosya ağacı ile açılır.

Zuplo Portal

Portal, projeyi varsayılan olarak yönetilen bir Git deposuna bağlar. Sonradan kendi GitHub, GitLab, Bitbucket veya Azure DevOps deponuzu Ayarlar’dan bağlayabilirsiniz.

Seçenek B: CLI Kullanarak

Yerel projeyi CLI ile başlatmak için:

npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

Geliştirme sunucusu 9000 portunda başlar ve Route Designer’a http://localhost:9100 üzerinden erişebilirsiniz. Yaptığınız değişiklikler otomatik olarak yansır.

Projeyi dağıtıma hazır hale getirmek ve Zuplo hesabınıza bağlamak için:

npx zuplo link
Enter fullscreen mode Exit fullscreen mode

Hesap ve ortam seçin. Sonrasında güncel dalı dağıtmak için:

npx zuplo deploy
Enter fullscreen mode Exit fullscreen mode

Adım 2: İlk Rotanızı Tanımlayın

config/routes.oas.json dosyasını açın. OpenAPI 3 dokümanı içinde aşağıdaki gibi bir rota ekleyin:

{
  "openapi": "3.1.0",
  "info": { "title": "Acme Ağ Geçidi", "version": "1.0.0" },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "Ürünleri listele",
        "operationId": "list-products",
        "x-zuplo-route": {
          "corsPolicy": "anything-goes",
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "${env.ORIGIN_URL}"
            }
          },
          "policies": { "inbound": [] }
        },
        "responses": {
          "200": { "description": "Başarılı" }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

x-zuplo-route altında handler ve policy’leri tanımlarsınız. ${env.ORIGIN_URL} ortam değişkeni ile farklı backend’lere yönlendirme yapabilirsiniz.

Ortam değişkenini portaldan veya yerelde config/.env dosyasına ekleyin. Kaydedin, değişiklikler anında yansır. Test için http://localhost:9000/v1/products adresine gidin.

Adım 3: API Anahtarı Kimlik Doğrulaması Ekleyin

Kamuya açık API’ler için kimlik doğrulama gerekir. Zuplo, yönetilen API anahtarı servisi sağlar.

Rota dosyanızda inbound policy’yi ekleyin:

"policies": {
  "inbound": ["api-key-auth"]
}
Enter fullscreen mode Exit fullscreen mode

Policy tanımını config/policies.json içerisine ekleyin:

{
  "name": "api-key-auth",
  "policyType": "api-key-inbound",
  "handler": {
    "export": "ApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Portal üzerinden Hizmetler > API Anahtar Servisi'ne gidin, “Tüketici Oluştur” ile yeni bir API anahtarı üretin.

Başlık olmadan test edin:

curl -i https://PROJENIZ.zuplo.app/v1/products
# HTTP/2 401
Enter fullscreen mode Exit fullscreen mode

Doğru başlıkla tekrar deneyin:

curl -i https://PROJENIZ.zuplo.app/v1/products \
  -H "Authorization: Bearer SIZIN_API_ANAHTARINIZ"
# HTTP/2 200
Enter fullscreen mode Exit fullscreen mode

Dilerseniz OpenAPI dökümanı ile Apidog'da test ortamı kurabilir, API anahtarınızı ortam değişkeni olarak bağlayabilirsiniz.

Adım 4: Hız Sınırı Ekleyin

API’nizi hız limiti olmadan yayınlamayın. Aşağıdaki şekilde inbound policy’lere ekleyin:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"]
}
Enter fullscreen mode Exit fullscreen mode

Policy tanımı:

{
  "name": "rate-limit-by-key",
  "policyType": "rate-limit-inbound",
  "handler": {
    "export": "RateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "rateLimitBy": "sub",
      "requestsAllowed": 60,
      "timeWindowMinutes": 1
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Her müşteri için 60 istek/dk sınırı. Aşağıdaki betikle test edin:

for i in {1..70}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    https://PROJENIZ.zuplo.app/v1/products \
    -H "Authorization: Bearer SIZIN_API_ANAHTARINIZ"
done | sort | uniq -c
Enter fullscreen mode Exit fullscreen mode

60 satır 200, 10 satır 429 görmelisiniz.

Adım 5: İstek Yüklerini Doğrulayın

Bir POST rotanız varsa, gövde şemasını OpenAPI ile tanımlayın:

"/v1/products": {
  "post": {
    "summary": "Ürün oluştur",
    "operationId": "create-product",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": ["name", "priceCents"],
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "priceCents": { "type": "integer", "minimum": 1 },
              "category": { "type": "string", "enum": ["food", "drink"] }
            }
          }
        }
      }
    },
    "x-zuplo-route": {
      "handler": { /* yukarıdakiyle aynı */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Policy tanımı:

{
  "name": "validate-request",
  "policyType": "open-api-request-validation-inbound",
  "handler": {
    "export": "OpenApiRequestValidationInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "validateBody": "reject"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Eksik veya hatalı gövdeler gateway’de 400 ile reddedilir. Apidog ile başarılı, eksik alanlı ve hatalı enum’lu fonksiyon testleri oluşturun.

Adım 6: Özel TypeScript Policy Yazın

Hazır policy’ler çoğu ihtiyacı karşılar. Ancak özel mantık gerekirse, örneğin ücretli müşterilere farklı cache davranışı eklemek için:

modules/tiered-cache.ts:

import { ZuploRequest, ZuploContext, HttpProblems } from "@zuplo/runtime";

interface PolicyOptions {
  paidPlanHeader: string;
  paidMaxAge: number;
}

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
  options: PolicyOptions,
): Promise<Response> {
  const plan = request.user?.data?.plan ?? "free";

  if (plan === "free") {
    response.headers.set("Cache-Control", "no-store");
  } else {
    response.headers.set(
      "Cache-Control",
      `public, max-age=${options.paidMaxAge}`,
    );
  }

  context.log.info(`Cache header set for plan=${plan}`);
  return response;
}
Enter fullscreen mode Exit fullscreen mode

Policy olarak ekleyin:

{
  "name": "tiered-cache",
  "policyType": "custom-code-outbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/tiered-cache)",
    "options": {
      "paidPlanHeader": "x-plan",
      "paidMaxAge": 300
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Rota dosyasında outbound policy olarak referans verin:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"],
  "outbound": ["tiered-cache"]
}
Enter fullscreen mode Exit fullscreen mode

Bu policy’yi Jest veya Vitest ile birim test edebilirsiniz.

Adım 7: Uca Dağıtım

Git ile dağıtım yapın:

git add .
git commit -m "Kimlik doğrulama, hız limiti ve cache policy eklendi"
git push origin feature/products-gateway
Enter fullscreen mode Exit fullscreen mode

Her dal için önizleme ortamı oluşur ve URL’i log’da görebilirsiniz. Önizleme URL’sini Apidog ile test edin. Her şey tamamsa ana dala birleştirin:

git checkout main
git merge feature/products-gateway
git push origin main
Enter fullscreen mode Exit fullscreen mode

Birleştirme otomatik olarak prod dağıtımını tetikler.

Adım 8: Geliştirici Portalı Oluşturun

Portalınız https://PROJENIZ.developers.zuplo.com adresinde barındırılır. İçerik:

  • Her rota için OpenAPI şeması, açıklama ve deneme konsolu
  • cURL, JS, Python, Go ve diğer dillerde kod örnekleri
  • Otomatik API anahtarı oluşturma
  • Markalama kontrolleri: Geliştirici Portalı > Ayarlar

OpenAPI şemanız yeterliyse, portal ekstra iş gerektirmez. Özelleştirmek için Zuplo Geliştirici Portalı kodunu çatallayabilirsiniz.

Adım 9: Tümünü Apidog ile Test Edin

Gateway’iniz yayında olduğunda, her rota ve policy’i Apidog ile test edin.

Apidog ile test

Önerilen süreç:

  1. OpenAPI şemanızı https://PROJENIZ.zuplo.app/openapi üzerinden içe aktarın.
  2. local, preview, production ortamları oluşturun ve uygun base_url/api_key girin.
  3. Her rota için başarılı, kimlik doğrulama hatalı ve hız limiti tetikleyen örnekler oluşturun.
  4. Apidog’un test senaryoları ile zincirli istekler kurun ve yanıtları doğrulayın.
  5. Dilediğiniz dilde kod örneklerini alın ve dokümanlarınıza ekleyin.

Postman’dan geçiş için API test rehberini izleyebilirsiniz. Apidog’u indirin ve sürecinize entegre edin.

Zuplo Kullanımı Hakkında Sık Sorulan Sorular

Bir rotayı spesifikasyonu değiştirmeden ortamlar arasında nasıl değiştiririm?

Ortam değişkenleri kullanın. Her ortam için Ayarlar veya config/.env dosyasına ORIGIN_URL tanımlayın, handler’da ${env.ORIGIN_URL} kullanın.

Zuplo'yu çevrimdışı çalıştırabilir miyim?

Evet. npm run dev ile 9000 portunda local gateway ve 9100 portunda Route Designer açılır. API anahtarı servisi hariç tüm özellikler offline çalışır. API anahtarı için npx zuplo link ile bulut hizmetine bağlanabilirsiniz.

Kötü bir dağıtımı nasıl geri alırım?

git revert ile son merge commit’ini geri alın ve push edin. Zuplo otomatik olarak eski sürümü yayına alır.

Dağıtım sırasında devam eden isteklere ne olur?

Dağıtımlar uçta atomiktir. Devam eden istekler eski sürümü bitirir, yeni istekler yeni sürüme gider.

Zuplo'yu gRPC veya WebSockets ile kullanabilir miyim?

Evet. urlForwardHandler WebSocket yükseltmesini ve gRPC ise ilgili handler ile desteklenir.

Zuplo API’mi AI araçlarına nasıl açarım?

Rotalara MCP Server Handler ekleyin, OpenAPI şemanıza işaret edin ve işlemleri seçin. Policy’ler MCP istekleri için de geçerlidir. MCP Server dökümantasyonu detaylıdır.

Üretimde ağ geçidi ne kadar tutar?

Ücretsiz katman ayda 100K istek kapsar. Builder planı aylık 25$’a 1M istek içerir, fazlası için 100K başına 100$ ücretlendirilir. Kurumsal fiyatlar için fiyatlandırma sayfasını inceleyin.

Sonuç

Artık API anahtarı doğrulama, anahtar başına hız limiti, istek doğrulama, özel TypeScript outbound policy ve geliştirici portalı içeren, Git ile global edge’e dağıtılan bir Zuplo gateway’iniz var. Aynı proje ile preview, prod ve AI agent erişimi yönetebilirsiniz.

Bunu stabil tutmanın yolu, test döngüsüdür. Her önizleme merge etmeden Apidog ile kimlik doğrulama hatalarını, eksik şema alanlarını ve yanlış hız limitlerini önceden yakalayın. Apidog’u indirin ve API gateway’inize bağlayın.

Top comments (0)