Cara Menggunakan API Zuplo: Panduan Lengkap

Jika Anda telah membaca tentang Zuplo dan ingin membuat sesuatu yang nyata dengannya, inilah postingan yang tepat untuk Anda. Platform ini cepat dipelajari, tetapi dokumentasinya tersebar di alur portal, perintah CLI, dan artikel pusat pembelajaran. Panduan ini menyatukan bagian-bagian tersebut menjadi satu tutorial: membuat proyek, mengekspos rute, menambahkan otentikasi kunci API dan pembatasan laju, menulis kebijakan TypeScript kustom, menerapkan ke edge, dan menguji semuanya dengan Apidog.

tombol

Pada akhirnya, Anda akan memiliki gateway API yang berfungsi yang berjalan di depan origin Anda, dengan otentikasi, pembatasan laju, portal pengembang yang dibuat secara otomatis, dan alur kerja Git yang ramah CI. Seluruh panduan ini memakan waktu sekitar tiga puluh menit.

Jika Anda masih memutuskan apakah Zuplo adalah alat yang tepat, mulailah dengan postingan pelengkap kami: Apa itu Zuplo API gateway. Untuk hal lainnya, dokumentasi Zuplo mencakup kasus-kasus ekstrem yang dilewati panduan ini.

TL;DR

Daftar di portal.zuplo.com atau buat proyek lokal dengan npm create zuplo.
Definisikan rute di config/routes.oas.json dan teruskan ke origin Anda dengan URL Forward Handler.
Tambahkan kebijakan inbound (autentikasi kunci API, batas laju, validasi skema) dengan mengedit file rute atau mengklik melalui Route Designer.
Tulis logika kustom sebagai modul TypeScript di modules/; runtime memberikan Anda akses bertipe ke permintaan, konteks, dan lingkungan.
Dorong ke cabang Git yang terhubung untuk menerapkan lingkungan pratinjau; gabungkan untuk diterapkan ke produksi di 300+ lokasi edge.
Uji setiap rute dengan Apidog sebelum mempromosikannya ke produksi.
Harga mulai gratis dengan 100 ribu permintaan per bulan; paket Builder adalah $25 per bulan.

Prasyarat

Anda membutuhkan tiga hal sebelum memulai:

Akun Zuplo
API origin untuk menempatkan gateway di depannya. Jika Anda tidak memilikinya, gunakan https://echo.zuplo.io, yang akan mengulang apa pun yang Anda kirimkan.
Node.js 18 atau lebih tinggi jika Anda berencana menggunakan CLI.

Untuk pengembangan lokal, Anda juga memerlukan editor kode. VS Code dengan ekstensi TypeScript adalah jalan termudah, dan Anda dapat memasangkannya dengan ekstensi Apidog VS Code untuk mengirim permintaan tanpa meninggalkan editor Anda.

Langkah 1: Buat proyek Zuplo Anda

Anda memiliki dua cara untuk memulai: portal web atau CLI. Sebagian besar tim memulai di portal karena lebih cepat untuk demo, kemudian bermigrasi ke CLI setelah mereka menginginkan CI/CD.

Opsi A: Mengutamakan Portal

Masuk di portal.zuplo.com.
Klik “New Project” dan pilih nama seperti acme-gateway.
Pilih “Empty Project” agar tidak ada yang dibuat secara otomatis.
Tab Code akan terbuka ke pohon file awal.

Secara default, portal menautkan proyek ke repo Git yang dikelola. Anda dapat menghubungkan repo GitHub, GitLab, Bitbucket, atau Azure DevOps Anda sendiri dari Pengaturan nanti.

Opsi B: Mengutamakan CLI

CLI membuat kerangka tata letak proyek yang sama secara lokal sehingga Anda dapat mengedit di IDE Anda dan menggunakan Git sejak hari pertama.

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

Server dev dimulai pada port 9000 dan mencetak tautan ke Route Designer lokal di http://localhost:9100. Setiap perubahan yang Anda buat di editor atau di desainer akan langsung di-hot-reload.

Untuk menautkan proyek lokal ke akun Zuplo Anda setelah Anda siap untuk menerapkan:

npx zuplo link

Pilih akun dan lingkungan saat diminta. Dari sini, npx zuplo deploy akan menerapkan cabang Git saat ini.

Langkah 2: Definisikan rute pertama Anda

Buka config/routes.oas.json. Ini adalah dokumen OpenAPI 3 dengan ekstensi Zuplo untuk handler dan kebijakan. Tambahkan rute yang meneruskan GET /v1/products ke origin Anda:

{
  "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" }
        }
      }
    }
  }
}

Beberapa detail penting untuk diperhatikan. Ekstensi x-zuplo-route adalah tempat Zuplo berada di dalam file OpenAPI yang "polos". handler menjelaskan apa yang terjadi saat rute cocok; urlForwardHandler adalah proksi bawaan. Referensi ${env.ORIGIN_URL} menarik dari variabel lingkungan sehingga Anda dapat menargetkan backend yang berbeda per lingkungan.

Atur ORIGIN_URL dari Settings > Environment Variables di portal, atau dengan mengedit config/.env secara lokal. Gunakan https://echo.zuplo.io jika Anda belum memiliki origin yang sesungguhnya.

Simpan dan server dev lokal akan memuat ulang. Kunjungi http://localhost:9000/v1/products dan Anda akan melihat permintaan yang diulang. Gateway yang diterapkan akan merespons dari pusat data edge terdekat.

Langkah 3: Tambahkan autentikasi kunci API

API publik memerlukan kredensial. Zuplo menyediakan layanan kunci API terkelola sehingga Anda tidak perlu membuat penyimpanan kunci sendiri.

Edit rute untuk menambahkan kebijakan inbound:

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

Kemudian tambahkan definisi kebijakan ke config/policies.json (Zuplo membuat file ini pertama kali Anda menambahkan kebijakan):

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

Sekarang buat konsumen (entitas yang memiliki satu atau lebih kunci API):

Buka Services > API Key Service di portal.
Klik “Create Consumer”.
Atur subjek ke pengidentifikasi stabil seperti acme-customer-1.
Tambahkan email siapa pun yang harus mengelola kunci.
Salin kunci API yang dihasilkan.

Uji dengan curl. Tanpa header, Anda akan melihat 401:

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

Dengan header, Anda akan melihat respons 200 yang asli:

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

Jika Anda lebih suka mengujinya dari klien sungguhan, impor spesifikasi OpenAPI gateway ke Apidog, atur header global untuk Authorization: Bearer {{api_key}}, dan kaitkan api_key dengan variabel lingkungan. Anda akan mendapatkan permukaan uji yang bersih untuk setiap rute dalam hitungan detik.

Langkah 4: Batasi laju rute

Jangan pernah merilis API publik tanpa pembatasan laju. Kebijakan pembatasan laju Zuplo default memberikan Anda pembatasan berdasarkan IP, berdasarkan kunci, atau berdasarkan atribut kustom.

Tambahkan ke daftar inbound, setelah otentikasi:

"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" mengunci *bucket* pada subjek yang diautentikasi dari kebijakan kunci API, sehingga setiap pelanggan mendapatkan anggaran 60 permintaan per menit mereka sendiri. Ganti dengan "ip" jika Anda ingin membatasi lalu lintas anonim.

Permintaan ke-61 dalam setiap jendela enam puluh detik akan mengembalikan 429 dengan header percobaan ulang terlampir. Uji dengan mengirim 70 permintaan dalam loop dan amati kode respons yang berubah.

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

Anda akan melihat 60 baris bertuliskan 200 dan 10 baris bertuliskan 429.

Langkah 5: Validasi payload permintaan

Jika Anda memiliki rute POST yang menerima body JSON, kebijakan validasi permintaan akan menangkap payload yang salah format di gateway, bukan di origin Anda. Ini menggunakan Skema JSON yang tertanam dalam operasi OpenAPI Anda, jadi Anda mendapatkan ini secara gratis jika spesifikasi Anda akurat.

Tambahkan rute dengan body permintaan:

"/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": { /* sama seperti di atas */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}

Tambahkan kebijakan:

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

Sekarang, permintaan POST dengan bidang yang hilang akan ditolak dengan kode 400 sebelum mencapai origin Anda. Uji dengan Apidog dengan menyimpan permintaan “happy path”, permintaan “bidang wajib yang hilang”, dan permintaan “nilai enum yang salah” sebagai contoh terpisah dalam grup permintaan yang sama. Anda dapat menjalankan ketiganya dengan satu klik.

Langkah 6: Tulis kebijakan TypeScript kustom

Kebijakan bawaan mencakup sebagian besar kebutuhan tim. Namun, poin Zuplo adalah saat Anda membutuhkan sesuatu yang kustom. Berikut adalah kebijakan outbound yang menambahkan header Cache-Control untuk pelanggan berbayar dan no-store untuk pelanggan gratis.

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;
}

Hubungkan ke 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 rujuk dari rute:

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

Kebijakan kustom hanyalah sebuah fungsi. Anda dapat menguji unitnya dengan Vitest atau Jest dengan meneruskan Response dan ZuploRequest sintetis dan melakukan penegasan pada header, tanpa memerlukan *harness* integrasi.

Langkah 7: Terapkan ke edge

Penerapan adalah sebuah *Git push*.

git add .
git commit -m "Tambahkan gateway produk dengan otentikasi, batas laju, dan cache berjenjang"
git push origin feature/products-gateway

Zuplo membangun lingkungan pratinjau untuk setiap cabang dan mencetak URL di log build. Pratinjau mendapatkan subdomainnya sendiri seperti https://acme-gateway-feature-products-gateway-abc123.zuplo.app, dengan semua kebijakan Anda aktif dan mengarah ke ORIGIN_URL apa pun yang diatur untuk lingkungan tersebut.

Uji URL pratinjau dengan Apidog dengan mengaturnya sebagai lingkungan baru di proyek Anda. Jalankan seluruh *test suite* Anda terhadapnya. Jika semuanya lolos, gabungkan cabangnya.

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

Penggabungan memicu penerapan produksi. Dalam waktu enam puluh detik, versi baru akan aktif di 300+ lokasi edge. Promosi dan *rollback* keduanya adalah operasi git push; tidak ada UI terpisah.

Langkah 8: Hasilkan portal pengembang

Portal di-host di https://YOUR-PROJECT.developers.zuplo.com dan dibangun ulang setiap kali diterapkan. Ini mencakup:

Satu halaman per rute, dengan skema, deskripsi, dan konsol coba-sendiri.
Contoh kode dalam cURL, JavaScript, Python, Go, dan beberapa lainnya.
Penerbitan kunci API swalayan untuk setiap pengunjung yang mendaftar.
Kontrol branding di portal di bawah Developer Portal > Settings.

Jika spesifikasi OpenAPI Anda memiliki deskripsi dan contoh yang baik, portal akan terlihat selesai tanpa pekerjaan lebih lanjut. Jika spesifikasi Anda tipis, inilah saatnya Anda mengetahuinya.

Untuk menyesuaikan, sumber portal dikirimkan sebagai aplikasi Next.js terpisah yang dapat Anda *fork* dari repo portal pengembang Zuplo di GitHub. Sebagian besar tim tetap menggunakan versi yang di-host.

Langkah 9: Uji semuanya dengan Apidog

Setelah gateway Anda aktif, disiplin yang mencegah insiden produksi adalah menguji setiap rute, setiap kebijakan, dan setiap jalur kesalahan. Apidog membuatnya cepat.

Alur kerja yang berfungsi dengan baik:

Impor spesifikasi OpenAPI gateway dari https://YOUR-PROJECT.zuplo.app/openapi. Apidog mengubah setiap operasi menjadi permintaan yang dapat Anda kirim.
Buat lingkungan untuk local, preview, dan production, masing-masing dengan base_url dan api_key-nya sendiri.
Simpan minimal tiga permintaan per rute: *happy path*, kegagalan otentikasi, dan pemicu batas laju. Jalankan sebagai grup sebelum setiap penerapan.
Gunakan skenario pengujian otomatis Apidog untuk merangkai panggilan bersama (membuat produk, mencantumkannya, menghapusnya) dan menegaskan bentuk respons.
Hasilkan contoh kode dalam bahasa utama tim Anda dan tempelkan ke *runbook* Anda.

Jika Anda bermigrasi dari Postman, panduan pengujian API tanpa Postman akan menjelaskan impornya. Unduh Apidog jika Anda belum melakukannya.

Pertanyaan umum tentang penggunaan Zuplo

Bagaimana cara saya mengganti rute antar lingkungan tanpa mengubah spesifikasi?

Gunakan variabel lingkungan. Definisikan ORIGIN_URL per lingkungan di Pengaturan portal atau di config/.env secara lokal, dan referensikan sebagai ${env.ORIGIN_URL} di dalam opsi handler. Rute tetap identik; hanya variabel yang berubah.

Bisakah saya menjalankan Zuplo secara offline?

Ya. npm run dev memulai gateway lokal pada port 9000 dengan Route Designer lokal pada 9100. Kebijakan kustom, validasi, dan pembatasan laju semuanya berfungsi secara lokal; satu-satunya hal yang memerlukan koneksi internet adalah layanan kunci API terkelola, dan Anda dapat menjalankan npx zuplo link untuk menggunakan layanan cloud dari instans lokal Anda.

Bagaimana cara saya melakukan rollback penerapan yang buruk?

git revert *merge commit* dan *push*. Zuplo akan menerapkan kembali status sebelumnya. Tidak ada tombol “rollback” terpisah karena riwayat Git adalah sumber kebenaran.

Apa yang terjadi pada permintaan yang sedang berjalan selama penerapan?

Penerapan bersifat atomik di *edge*; permintaan yang sedang berjalan selesai pada versi lama dan permintaan baru mengenai versi baru. Tidak ada jendela *downtime*.

Bisakah saya menggunakan Zuplo dengan gRPC atau WebSockets?

Ya. urlForwardHandler memproksi pemutakhiran WebSocket secara transparan, dan gRPC didukung melalui handler gRPC. REST dan GraphQL adalah kelas satu dan kasus yang paling umum.

Bagaimana cara saya mengekspos API Zuplo saya ke agen AI?

Tambahkan MCP Server Handler ke sebuah rute, arahkan ke spesifikasi OpenAPI Anda, dan pilih operasi yang akan diekspos. Kebijakan otentikasi dan pembatasan laju yang sama berlaku untuk permintaan MCP. Dokumentasi Zuplo MCP Server mencakup pengaturan tersebut.

Berapa biaya gateway dalam produksi?

Tingkat gratis mencakup 100 ribu permintaan per bulan. Paket Builder menambahkan 1 juta permintaan seharga $25 per bulan, dan permintaan tambahan berharga $100 per 100 ribu. Harga enterprise dimulai dari $1.000 per bulan dengan kontrak tahunan. Rincian lengkap ada di halaman harga Zuplo.

Kesimpulan

Anda sekarang memiliki gateway Zuplo yang berfungsi dengan otentikasi kunci API, pembatasan laju per kunci, validasi permintaan, kebijakan outbound TypeScript kustom, dan portal pengembang, semuanya diterapkan melalui Git ke edge global. Proyek yang sama menangani lingkungan pratinjau, peluncuran produksi, dan akses agen AI melalui MCP.

Bagian yang menjaganya tetap stabil adalah loop pengujian. Gunakan Apidog pada setiap pratinjau sebelum digabungkan, dan Anda akan menangkap header otentikasi yang rusak, bidang skema yang hilang, dan batas laju yang secara tidak sengaja terlalu murah hati sebelum diterapkan. Unduh Apidog dan hubungkan ke gateway Anda hari ini.

tombol