Cara Membuat Kode Klien dari API Spec di Apidog

Anda memiliki endpoint yang sudah didefinisikan dan ingin memanggilnya dari aplikasi. Bagian yang sering memakan waktu adalah menerjemahkan spesifikasi menjadi kode yang benar: URL, header, token autentikasi, query string, dan pemanggilan requests atau fetch. Satu karakter yang salah dapat berujung pada respons 401 dan proses debugging yang tidak perlu.

Coba Apidog hari ini

Anda tidak perlu menulis boilerplate tersebut secara manual. Jika API dirancang di Apidog, platform ini membaca spesifikasi endpoint dan menghasilkan potongan kode permintaan siap tempel, seperti cURL, Python requests, JavaScript fetch, atau Axios. Artikel ini menunjukkan cara menghasilkan kode dari endpoint, kapan harus mengirim permintaan terlebih dahulu agar kode berisi nilai aktual, serta cara menjaga hasilnya tetap sinkron dengan spesifikasi. Untuk pilihan yang lebih luas, lihat rangkuman alat pembuatan kode API.

Prinsip utamanya adalah menjadikan spesifikasi sebagai satu-satunya sumber kebenaran, sejalan dengan Spesifikasi OpenAPI. Perbarui definisi API sekali, lalu hasilkan ulang kode permintaan dari definisi tersebut.

Apa yang dilakukan generator kode klien?

Apidog mengubah definisi endpoint menjadi potongan kode untuk satu permintaan HTTP dalam bahasa dan pustaka yang Anda pilih.

Misalnya, untuk GET /orders:

1. Buka endpoint tersebut.
2. Pilih Python.
3. Pilih varian Requests.
4. Salin kode yang dihasilkan.

Generator akan membuat panggilan yang menggunakan path, header, dan parameter yang dideklarasikan pada spesifikasi.

Fitur ini menghasilkan kode permintaan per endpoint, bukan SDK lengkap dengan model, pagination helper, atau paket klien berversi.

Gunakan hasil generator saat Anda membutuhkan cURL, fetch, Axios, atau requests.get yang sesuai dengan kontrak API saat ini. Pendekatan ini cocok untuk pengembangan API yang mengutamakan desain: definisikan kontrak, lalu turunkan kode klien dari kontrak yang sama.

Dua cara membuka generator

Apidog menyediakan dua titik masuk untuk generator kode klien.

Dari tab Dokumentasi

Gunakan jalur ini saat Anda sedang membaca dokumentasi endpoint:

1. Buka tab Dokumentasi API.
2. Pilih endpoint yang ingin digunakan.
3. Klik Hasilkan Kode Klien di sisi kanan.
4. Pilih bahasa dan varian pustaka.

Dari tab Jalankan

Gunakan jalur ini saat Anda sudah menguji permintaan:

1. Buka tab Jalankan.
2. Isi parameter, header, dan body jika diperlukan.
3. Klik ikon kode </> di area pembuat permintaan.
4. Pilih bahasa dan varian pustaka.

Kedua jalur membuka panel generator yang sama. Perbedaannya hanya pada konteks kerja Anda: dokumentasi untuk melihat kontrak, atau runner untuk menghasilkan kode dari permintaan yang sudah diuji.

Hasilkan panggilan Python untuk GET /orders

Contoh berikut menggunakan GET /orders untuk mengambil daftar pesanan berdasarkan status dan halaman.

Langkah 1: pilih bahasa dan pustaka

Buka tab Dokumentasi, klik Hasilkan Kode Klien, lalu pilih Python dan Requests.

Apidog menyediakan beberapa target, termasuk:

• Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
• JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
• Python: http.client, Requests
• Java: Unirest, OkHttp
• Go: Native
• PHP: cURL, Guzzle, pecl_http, HTTP_Request2
• Lainnya: Swift, C, C#, Objective-C, Ruby, OCaml, Dart, R, dan HTTP mentah

Contoh hasil untuk Python Requests:

import requests

url = "https://api.example.com/orders"

querystring = {
    "status": "shipped",
    "page": "1",
}

headers = {
    "Accept": "application/json",
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

Sebelum memasukkan kode ke aplikasi, sesuaikan tiga bagian berikut:

• url: gunakan base URL lingkungan yang benar.
• querystring: isi parameter yang benar untuk kasus penggunaan Anda.
• headers: tambahkan autentikasi bila endpoint membutuhkannya.

Langkah 2: pahami batas kode dari spesifikasi

Kode yang dihasilkan langsung dari spesifikasi biasanya mencakup struktur permintaan, tetapi tidak selalu menyertakan nilai runtime aktual seperti:

• token Bearer;
• API key;
• nilai variabel lingkungan;
• parameter yang Anda isi manual saat pengujian.

Dengan kata lain, generator dari dokumentasi memberikan template yang sesuai kontrak. Ini cukup untuk endpoint publik atau saat Anda akan mengisi kredensial sendiri melalui konfigurasi aplikasi.

Untuk endpoint terlindungi seperti GET /orders, hasil yang paling praktis biasanya berasal dari permintaan yang sudah dikirim.

Langkah 3: kirim permintaan untuk menangkap nilai aktual

Agar kode mencerminkan nilai parameter dan header yang benar-benar dikirim:

1. Buka tab Jalankan.
2. Pastikan metode dan URL endpoint benar.
3. Isi parameter status dan page.
4. Tambahkan autentikasi, misalnya Authorization: Bearer <token>.
5. Klik Kirim.
6. Setelah respons diterima, buka tab Permintaan Aktual.
7. Salin kode klien dari bagian tersebut.

Contoh hasilnya:

import requests

url = "https://api.example.com/orders"

querystring = {
    "status": "shipped",
    "page": "1",
}

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer sk_live_51H8xY2..."
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

Jika Anda bekerja dengan pendekatan design-first, parameter awal dapat terisi dari spesifikasi. Dalam mode request-first, Anda dapat menambahkan parameter secara manual di tab Jalankan. Setelah menekan Kirim, keduanya dapat menghasilkan kode dari Permintaan Aktual.

Jangan commit token asli ke Git. Gunakan variabel lingkungan atau secret manager. Praktik ini sama pentingnya dengan rekomendasi pada dokumentasi Stripe untuk kunci live.

Versi yang lebih aman untuk aplikasi Python:

import os
import requests

url = "https://api.example.com/orders"

params = {
    "status": "shipped",
    "page": 1,
}

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.environ['API_TOKEN']}",
}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()

orders = response.json()
print(orders)

Menangani request body untuk POST dan PUT

GET /orders tidak memiliki body. Namun, POST /orders atau PUT /orders/{id} memerlukan request body yang sesuai dengan skema API.

Di tab Jalankan, Anda dapat membuat body JSON atau XML dari:

1. contoh yang sudah didefinisikan pada spesifikasi; atau
2. opsi Hasilkan Otomatis.

Dropdown Hasilkan Otomatis menyediakan dua mode:

• Contoh: gunakan contoh request body yang telah didefinisikan secara manual.
• Hasilkan Setiap Kali: buat nilai baru setiap kali digunakan mengikuti aturan mock dan skema.

Anda juga dapat mengatur Preferensi Hasilkan Otomatis:

• Gunakan Nilai Contoh Terlebih Dahulu
• Gunakan Nilai Default Terlebih Dahulu
• Gunakan Nilai Mock
• Hasilkan Nama Bidang Saja
• Gunakan Contoh Permintaan

Gunakan Gunakan Nilai Contoh Terlebih Dahulu jika spesifikasi sudah memiliki contoh yang representatif. Gunakan Gunakan Nilai Mock jika Anda perlu data uji yang realistis untuk setiap bidang.

Contoh body untuk POST /orders:

{
  "customer_id": "cus_123",
  "items": [
    {
      "product_id": "prod_456",
      "quantity": 2
    }
  ],
  "shipping_address": {
    "city": "Jakarta",
    "postal_code": "10110"
  }
}

Setelah body siap:

1. Klik Kirim.
2. Verifikasi respons API.
3. Buka tab Permintaan Aktual.
4. Salin kode dalam bahasa pilihan Anda.

Saat nilai harus berubah setiap permintaan, seperti timestamp atau ID acak, gunakan nilai dinamis alih-alih hard-code. Klik ikon tongkat ajaib di samping input parameter, atau gunakan Sisipkan Nilai Dinamis dalam body JSON/XML.

Opsi Hasilkan Otomatis untuk request body memerlukan Apidog versi 2.7.0 atau lebih baru. Jika opsi belum muncul, perbarui aplikasi.

Spesifikasi dengan skema dan contoh yang baik—misalnya dari pembuatan otomatis dokumentasi API dari OpenAPI—akan menghasilkan body yang memerlukan lebih sedikit pengeditan manual.

Kapan memakai potongan permintaan vs kode aplikasi?

Gunakan potongan kode tunggal seperti cURL, fetch, atau requests.get untuk pekerjaan one-off:

• memeriksa penyebab respons 403;
• membagikan permintaan yang dapat direproduksi dalam tiket;
• menjalankan pemeriksaan cepat dari terminal;
• menambahkan contoh API ke dokumentasi internal.

Contoh cURL yang cocok untuk debugging:

curl --request GET \
  --url 'https://api.example.com/orders?status=shipped&page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_TOKEN"

Gunakan bentuk kode yang lebih terstruktur saat panggilan akan menjadi bagian aplikasi. Misalnya, bungkus GET /orders dalam fungsi layanan agar penanganan kesalahan, autentikasi, dan penggunaan ulang tidak tersebar di banyak file.

import os
import requests


class OrdersClient:
    def __init__(self, base_url: str):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            "Accept": "application/json",
            "Authorization": f"Bearer {os.environ['API_TOKEN']}",
        })

    def list_orders(self, status: str, page: int = 1):
        response = self.session.get(
            f"{self.base_url}/orders",
            params={"status": status, "page": page},
            timeout=30,
        )
        response.raise_for_status()
        return response.json()

Jika banyak endpoint memakai autentikasi yang sama, pusatkan konfigurasi tersebut. Panduan mengatur parameter global di Apidog menjelaskan cara mendefinisikan header dan variabel sekali agar permintaan dapat mewarisinya.

Jaga akurasi dengan kebiasaan spec-first

Kode yang dihasilkan hanya akan akurat jika spesifikasinya akurat.

Misalnya, Anda menambahkan parameter query region ke GET /orders, tetapi tetap memakai potongan kode lama. Klien Anda tidak akan mengirim parameter baru tersebut meskipun kontrak API telah berubah.

Terapkan alur berikut setiap kali ada perubahan endpoint:

1. Perbarui spesifikasi API.
2. Simpan dan tinjau perubahan kontrak.
3. Jalankan permintaan di tab Jalankan.
4. Verifikasi respons.
5. Hasilkan ulang potongan kode.
6. Perbarui kode aplikasi dan pengujian bila diperlukan.

Mode spec-first Apidog membantu menjaga definisi tetap otoritatif sehingga kode yang dihasilkan mencerminkan kontrak terbaru.

Untuk memahami atau menyesuaikan kode JavaScript yang dihasilkan, gunakan dokumentasi MDN tentang Fetch API sebagai referensi.

Otomatiskan validasi dengan Apidog CLI

Pembuatan kode klien dilakukan dari GUI; tidak ada perintah CLI terpisah yang mengeluarkan kode klien. Namun, Apidog CLI berguna untuk menjaga fondasi kode tersebut: spesifikasi yang mutakhir dan pengujian API yang lulus.

Instal CLI:

npm install -g apidog-cli

Apidog CLI memerlukan Node.js v16+.

Kemudian autentikasi:

apidog login --with-token <YOUR_ACCESS_TOKEN>

Jalankan skenario pengujian tersimpan untuk memverifikasi endpoint yang digunakan klien:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Parameter yang digunakan:

• -t: ID skenario pengujian
• -e: ID lingkungan
• -r: reporter seperti cli, html, atau junit

Tambahkan perintah ini ke pipeline CI. Panduan Apidog CLI GitHub Actions menunjukkan cara menjalankannya saat ada push. Dengan begitu, perubahan kontrak yang merusak dapat terdeteksi sebelum tim menghasilkan ulang atau memperbarui kode klien.

FAQ

Apakah kode yang dihasilkan menyertakan API key dan token?

Tidak secara default. Kode dari spesifikasi umumnya berisi struktur permintaan, bukan nilai autentikasi aktual. Untuk mendapatkan kode yang mencerminkan token dan parameter yang benar-benar dikirim, jalankan permintaan terlebih dahulu lalu salin dari tab Permintaan Aktual.

Tetap perlakukan token di potongan kode sebagai rahasia.

Bahasa dan pustaka apa yang didukung?

Apidog mendukung banyak target, termasuk Shell, JavaScript, Python, Java, Go, PHP, Swift, C, C#, Ruby, Dart, R, dan lainnya. Untuk beberapa bahasa, Anda juga dapat memilih varian pustaka seperti Fetch, Axios, Requests, OkHttp, atau cURL.

Mengapa opsi Hasilkan Otomatis tidak muncul untuk request body?

Opsi tersebut memerlukan Apidog versi 2.7.0 atau lebih baru. Setelah aplikasi diperbarui, opsi akan tersedia di tab Jalankan saat Anda menyusun body JSON atau XML.

Apakah pembuatan kode klien merupakan fitur berbayar?

Dokumentasi Apidog tidak membedakan ketersediaan pembuatan kode klien berdasarkan gratis atau berbayar, maupun cloud atau self-hosted. Persyaratan versi yang disebutkan adalah Apidog 2.7.0 atau lebih baru untuk opsi Hasilkan Otomatis pada request body.

Anda dapat mengunduh Apidog dan mencoba generatornya.

Bagaimana cara memastikan kode yang dihasilkan benar-benar berfungsi?

Gunakan proses berikut:

1. Hasilkan potongan kode.
2. Jalankan permintaan di Apidog.
3. Buat skenario pengujian untuk endpoint tersebut.
4. Jalankan skenario secara lokal atau di CI menggunakan CLI.

Panduan menulis skenario pengujian dengan Apidog menjelaskan cara membuat skenario tersebut.

Ringkasan

Generator kode klien di Apidog mengubah spesifikasi endpoint menjadi permintaan siap pakai dalam bahasa dan pustaka pilihan Anda. Gunakan generator dari dokumentasi untuk mendapatkan struktur permintaan dari kontrak API, atau gunakan tab Permintaan Aktual setelah mengirim permintaan untuk mendapatkan parameter dan header aktual.

Pertahankan spesifikasi sebagai sumber kebenaran, hasilkan ulang kode setelah kontrak berubah, dan jalankan pengujian tersimpan untuk memverifikasi bahwa endpoint masih bekerja seperti yang diharapkan. Unduh Apidog, definisikan GET /orders, lalu hasilkan panggilan klien yang dapat langsung Anda gunakan.