Walse

Posted on Apr 27 • Originally published at apidog.com

Cara Menggunakan API Zuplo: Panduan Lengkap

Jika Anda telah membaca tentang Zuplo dan ingin langsung membuat sesuatu yang nyata, berikut adalah panduan langkah-demi-langkah yang bisa Anda terapkan. Dokumentasi Zuplo tersebar antara portal, CLI, dan artikel, sehingga tutorial ini menggabungkan semuanya menjadi satu referensi: mulai dari membuat proyek, menambahkan rute, mengaktifkan autentikasi kunci API dan pembatasan laju, menulis kebijakan TypeScript kustom, menerapkan ke edge, hingga menguji seluruh workflow dengan Apidog.

Coba Apidog hari ini

Pada akhir panduan, Anda akan memiliki gateway API yang berjalan di depan origin, lengkap dengan autentikasi, pembatasan laju, portal developer otomatis, dan alur kerja Git yang siap CI. Waktu yang dibutuhkan sekitar 30 menit.

Jika Anda ingin mengenal Zuplo lebih jauh, baca juga: Apa itu Zuplo API gateway. Dokumentasi lengkapnya ada di dokumentasi Zuplo.

TL;DR

Daftar di portal.zuplo.com atau buat proyek lokal dengan npm create zuplo.
Definisikan rute di config/routes.oas.json, lalu teruskan ke origin dengan URL Forward Handler.
Tambahkan kebijakan inbound (autentikasi API key, rate limit, validasi skema) di file rute atau melalui Route Designer.
Tulis logika kustom sebagai modul TypeScript di modules/.
Push ke cabang Git untuk menerapkan ke lingkungan pratinjau. Merge ke production di 300+ lokasi edge.
Uji setiap rute menggunakan Apidog sebelum produksi.
Harga mulai gratis untuk 100 ribu request/bulan; paket Builder $25/bulan.

Prasyarat

Sebelum mulai, pastikan Anda memiliki:

Akun Zuplo
API origin (bisa gunakan https://echo.zuplo.io jika belum punya backend sendiri)
Node.js 18+ (jika menggunakan CLI)
Editor kode (VS Code + ekstensi TypeScript sangat disarankan). Anda bisa memasang ekstensi Apidog di VS Code untuk testing API langsung di editor.

Langkah 1: Buat Proyek Zuplo Anda

Opsi A: Portal Web

Login di portal.zuplo.com.
Klik “New Project”, beri nama (misal: acme-gateway).
Pilih “Empty Project”.
Tab Code akan menampilkan struktur file awal.

Secara default, proyek diportal terhubung ke repo Git yang dikelola. Anda bisa menghubungkan repo GitHub/GitLab/Bitbucket/Azure DevOps sendiri lewat Settings.

Opsi B: CLI

Untuk workflow lokal & CI/CD:

npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev

Server dev aktif di port 9000, Route Designer di http://localhost:9100. Perubahan di editor akan auto reload.

Untuk menautkan ke akun Zuplo dan deploy:

npx zuplo link
# Pilih akun & environment
npx zuplo deploy

Langkah 2: Definisikan Rute Pertama

Edit config/routes.oas.json (OpenAPI 3 + ekstensi Zuplo). Contoh rute GET /v1/products yang diteruskan ke origin:

{
  "openapi": "3.1.0",
  "info": { "title": "Acme Gateway", "version": "1.0.0" },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "List products",
        "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": "Success" }
        }
      }
    }
  }
}

x-zuplo-route adalah ekstensi khusus Zuplo.
Handler urlForwardHandler memproksi ke origin.
${env.ORIGIN_URL} diambil dari variabel lingkungan (atur di portal atau di config/.env).

Coba akses ke http://localhost:9000/v1/products. Jika origin Anda adalah https://echo.zuplo.io, response akan mengulang request Anda.

Langkah 3: Tambahkan Autentikasi API Key

Zuplo menyediakan layanan API key terkelola.

Tambahkan kebijakan di rute:

"policies": {
  "inbound": ["api-key-auth"]
}

Definisikan kebijakan di config/policies.json:

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

Buat konsumen API key:

Buka Services > API Key Service di portal.
Klik “Create Consumer”.
Isi subjek unik (misal: acme-customer-1).
Tambahkan email admin key.
Salin API key yang dihasilkan.

Uji:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# HTTP/2 401

curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200

Untuk testing lebih mudah, impor spesifikasi OpenAPI ke Apidog, atur header global Authorization: Bearer {{api_key}}, dan gunakan variabel environment.

Langkah 4: Batasi Laju Rute (Rate Limiting)

Jangan rilis API publik tanpa rate limit!

Tambahkan ke inbound policies:

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

Definisikan di config/policies.json:

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

rateLimitBy: "sub" = rate limit per konsumen API key.

Uji dengan loop:

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

Output: 60x 200, 10x 429.

Langkah 5: Validasi Payload Request

Untuk rute POST dengan JSON body, validasi schema di level gateway.

Contoh rute:

"/v1/products": {
  "post": {
    "summary": "Create product",
    "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": {/* ... */},
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}

Definisikan policy:

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

Coba kirim request POST dengan payload salah, Anda akan dapat error 400 sebelum request ke origin. Simpan skenario happy path & gagal di Apidog, jalankan semua sekaligus.

Langkah 6: Kebijakan TypeScript Kustom

Jika policy bawaan tidak cukup, tulis policy sendiri.

Contoh outbound policy untuk header cache berdasarkan plan:
Buat 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;
}

Daftarkan di config/policies.json:

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

Dan aktifkan di rute:

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

Policy kustom bisa dites unit dengan Vitest/Jest.

Langkah 7: Deploy ke Edge

Proses deploy = git push.

git add .
git commit -m "Tambahkan gateway produk dengan otentikasi, rate limit, cache"
git push origin feature/products-gateway

Zuplo otomatis membangun preview environment per branch, URL akan dicetak di log build (misal: https://acme-gateway-feature-products-gateway-abc123.zuplo.app). Uji di Apidog dengan membuat environment baru.

Merge branch ke main untuk production:

git checkout main
git merge feature/products-gateway
git push origin main

Deployment production selesai <60 detik di 300+ edge. Rollback tinggal git revert + push.

Langkah 8: Portal Developer Otomatis

Portal otomatis tersedia di https://YOUR-PROJECT.developers.zuplo.com:

Satu halaman per rute, lengkap dengan schema, deskripsi, dan “try it now”
Contoh kode: cURL, JS, Python, Go, dsb.
Penerbitan API key swalayan
Kontrol branding di Developer Portal > Settings

Jika OpenAPI Anda lengkap, portal langsung siap pakai. Untuk customisasi penuh, Anda bisa fork repo portal developer Zuplo di GitHub.

Langkah 9: Uji Semua Workflow dengan Apidog

Setiap rute, policy, dan error path wajib diuji sebelum release. Apidog sangat efisien untuk ini.

Workflow uji yang direkomendasikan:

Import spesifikasi OpenAPI dari https://YOUR-PROJECT.zuplo.app/openapi ke Apidog.
Buat environment untuk local, preview, dan production (set base_url, api_key masing-masing).
Simpan minimal tiga request per rute: happy path, gagal autentikasi, trigger rate limit.
Gunakan skenario pengujian otomatis Apidog untuk chaining dan asersi respons.
Generate kode contoh untuk dokumentasi/runbook tim.

Migrasi dari Postman? Ikuti panduan pengujian API tanpa Postman. Download Apidog di sini.

Pertanyaan Umum Tentang Penggunaan Zuplo

Bagaimana cara mengganti origin antar environment tanpa ubah spesifikasi?

Gunakan variabel environment. Definisikan ORIGIN_URL per environment di portal atau config/.env, lalu gunakan ${env.ORIGIN_URL} pada handler.

Bisakah menjalankan Zuplo offline?

Bisa. Jalankan npm run dev untuk gateway lokal (port 9000), Route Designer (9100). Semua policy lokal berjalan, kecuali layanan API key terkelola (memerlukan cloud). Gunakan npx zuplo link untuk menghubungkan cloud services dari lokal.

Bagaimana rollback deployment?

git revert merge commit lalu push. Zuplo akan menerapkan versi sebelumnya. Tidak ada tombol rollback—semua berdasarkan riwayat Git.

Apa yang terjadi pada request yang sedang berjalan saat deploy?

Deployment bersifat atomik di edge: request yang berjalan tetap di versi lama, request baru ke versi baru. Tidak ada downtime.

Apakah Zuplo support gRPC/WebSockets?

Ya. urlForwardHandler transparan untuk WebSocket upgrade, dan gRPC didukung via gRPC handler. REST & GraphQL juga didukung penuh.

Bagaimana expose API Zuplo ke agen AI?

Tambahkan MCP Server Handler ke rute, arahkan ke OpenAPI spec, pilih operasi yang diekspos. Kebijakan otentikasi dan rate limit tetap berlaku. Lihat dokumentasi Zuplo MCP Server.

Berapa biaya gateway Zuplo di produksi?

Free tier: 100.000 request/bulan. Builder plan: 1 juta request seharga $25/bulan, request tambahan $100 per 100k. Enterprise mulai $1.000/bulan. Detail harga di sini.

Kesimpulan

Sekarang Anda memiliki API gateway Zuplo yang siap produksi: autentikasi kunci API, rate limit per key, validasi request, kebijakan outbound TypeScript kustom, dan portal developer otomatis. Semua deployment dan rollback cukup dengan Git.

Loop pengujian adalah kunci stabilitas. Gunakan Apidog untuk testing di setiap preview sebelum merge. Ini akan membantu Anda mendeteksi error header, schema, dan policy sebelum sampai ke production. Download Apidog dan hubungkan ke gateway Anda sekarang juga.

DEV Community