DEV Community

Cover image for Cara Mock API dari CLI
Walse
Walse

Posted on • Originally published at apidog.com

Cara Mock API dari CLI

Anda membutuhkan API palsu untuk membangun aplikasi ketika backend belum siap, layanan pihak ketiga terkena rate limit, atau tes harus berjalan tanpa menyentuh server langsung. Solusi umumnya adalah mock, tetapi tantangan sebenarnya adalah membuatnya dapat direproduksi.

Coba Apidog hari ini

Anda dapat menentukan rute dan respons melalui GUI, tetapi mock yang dibuat manual di aplikasi desktop sulit direproduksi, sulit diberi versi, dan tidak bisa dibuat ulang secara mandiri oleh CI atau agen pengodean AI. Sebaliknya, mock dari CLI adalah perintah yang dapat dimasukkan ke skrip, pipeline, dan dokumentasi proyek. Apa yang Anda jalankan secara manual, mesin juga dapat menjalankannya.

Panduan ini membahas dua jalur:

  1. Jalur open-source: menjalankan server mock langsung dari file spesifikasi atau JSON.
  2. Jalur CLI Apidog: mengimpor spesifikasi ke proyek dan mengelola respons mock yang di-hosting.

Untuk membandingkan opsi sebelum memilih, lihat rangkuman alat mock API terbaik dan alat mocking API REST.

Jalur umum: menjalankan server mock dari sebuah file

Mock CLI klasik biasanya berupa binary kecil yang diarahkan ke sebuah file. Berikan file spesifikasi atau data, lalu alat tersebut menyajikan endpoint HTTP nyata pada porta lokal.

Tidak ada proyek, login, atau akun. Tiga alat berikut mencakup sebagian besar kebutuhan.

Prism: menyajikan spesifikasi OpenAPI

Jika Anda sudah memiliki file OpenAPI, Prism dari Stoplight adalah salah satu cara tercepat untuk menjalankan mock berbasis kontrak.

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Perintah tersebut memulai server pada http://127.0.0.1:4010 dan menghubungkan setiap operasi dalam spesifikasi Anda.

Prism akan:

  • Mengembalikan example yang didefinisikan dalam respons OpenAPI.
  • Menghasilkan data acak yang valid berdasarkan skema jika contoh tidak tersedia.
  • Memvalidasi permintaan masuk terhadap spesifikasi.
  • Mengembalikan 422 untuk permintaan yang tidak sesuai kontrak.

Uji endpoint untuk memastikan server berjalan:

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

Prism bersifat stateless. Permintaan POST tidak menyimpan data, sehingga alat ini cocok untuk memastikan klien tetap mematuhi kontrak API.

Untuk instalasi global:

npm install -g @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

Setelah itu, Anda dapat menjalankan prism tanpa npx.

Mockoon CLI: menjalankan file data tanpa GUI (headless)

Mockoon CLI menjalankan mock dari file data. File tersebut dapat berupa lingkungan yang diekspor dari aplikasi desktop Mockoon atau file OpenAPI JSON/YAML.

npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Arahkan opsi --data ke file lingkungan Mockoon atau file OpenAPI. Secara default, server berjalan pada porta 3000.

Gunakan --port untuk mengganti porta:

npx @mockoon/cli start --data ./env.json --port 4000
Enter fullscreen mode Exit fullscreen mode

Jika file berasal dari versi Mockoon yang lebih lama, CLI memigrasikannya di memori tanpa mengubah file asli.

Untuk instalasi global:

npm install -g @mockoon/cli
Enter fullscreen mode Exit fullscreen mode

Kemudian gunakan perintah persisten:

mockoon-cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Mockoon CLI cocok jika Anda membutuhkan rute dan respons yang dikustomisasi secara manual, tetapi tetap ingin menjalankannya di CI atau server tanpa GUI. Pendekatan ini juga sesuai untuk membangun server mock ringan untuk API RESTful.

json-server: memalsukan API REST dari JSON

Jika Anda belum memiliki spesifikasi API, json-server adalah jalur tercepat. Anda cukup menulis file JSON yang berisi data awal.

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

Contoh db.json:

{
  "posts": [
    {
      "id": 1,
      "title": "Mock API dari JSON",
      "published": true
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Perintah tersebut menyajikan endpoint berikut:

http://localhost:3000/posts
Enter fullscreen mode Exit fullscreen mode

Anda langsung mendapatkan operasi REST:

  • GET /posts
  • POST /posts
  • PUT /posts/:id
  • PATCH /posts/:id
  • DELETE /posts/:id

Berbeda dari Prism, json-server bersifat stateful. Permintaan POST benar-benar menambahkan data dan menuliskannya kembali ke file JSON. Anda juga dapat menggunakan pemfilteran, pengurutan, dan paginasi melalui parameter kueri.

Instal secara global jika diperlukan:

npm install -g json-server
Enter fullscreen mode Exit fullscreen mode

Ketiga alat tersebut adalah jalur open: satu binary, satu file input, dan server lokal. Kekurangannya, mock, desain API, tes, dan dokumentasi dapat hidup di tempat terpisah sehingga Anda perlu menjaga semuanya tetap sinkron secara manual.

Jika membutuhkan pencocokan permintaan atau pemutaran ulang yang lebih presisi, MockServer dan WireMock menawarkan kemampuan lebih dalam, dengan biaya runtime Java.

Jalur CLI Apidog: mengimpor spesifikasi dan membuat skrip ekspektasi

Apidog bekerja dengan model yang berbeda. CLI apidog tidak menjalankan server mock lokal dari sebuah file.

Tidak ada perintah seperti ini:

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Sebagai gantinya, Apidog menghosting mock untuk Anda. CLI digunakan untuk mengimpor spesifikasi dan mengelola respons mock kustom.

Apidog bukan open source; ini adalah produk komersial dengan tingkatan gratis. Nilai utamanya adalah integrasi: desain API, mock, dan tes berada dalam satu proyek sehingga dapat menggunakan satu sumber kebenaran.

Jika Anda hanya memerlukan server sementara dari satu file, Prism, Mockoon CLI, atau json-server biasanya lebih ringan. Jika mock harus tetap selaras dengan definisi API saat berubah, gunakan alur Apidog.

Instal CLI dan autentikasi terlebih dahulu. Panduan instalasi Apidog CLI menjelaskan pengaturan token.

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Impor spesifikasi untuk mendapatkan mock pintar yang di-hosting

Masukkan API Anda ke dalam proyek Apidog dengan mengimpor file OpenAPI:

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Setelah impor, Apidog menghasilkan URL mock yang di-hosting untuk setiap endpoint.

Berbeda dari Prism atau json-server, Anda tidak menjalankan proses server lokal. Smart mock Apidog membaca tipe dan nama bidang dari skema Anda. Misalnya:

  • Bidang email menghasilkan format email yang masuk akal.
  • Bidang createdAt menghasilkan timestamp yang terlihat realistis.
  • Respons mengikuti struktur skema API.

Selain OpenAPI, apidog import juga menerima format Swagger 2.0, Postman, dan Apidog.

Membuat skrip respons kustom dengan apidog mock

Mock otomatis cukup untuk kasus umum. Namun, Anda mungkin membutuhkan respons berbeda berdasarkan permintaan tertentu, misalnya:

  • GET /users/1 mengembalikan 200.
  • GET /users/999 mengembalikan 404.

Untuk kebutuhan ini, buat ekspektasi mock. Grup perintah apidog mock mengelola ekspektasi tersebut sebagai operasi CRUD, bukan sebagai server lokal.

Lihat perintah yang tersedia:

apidog mock --help
Enter fullscreen mode Exit fullscreen mode

Daftarkan ekspektasi dalam proyek:

apidog mock list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Batasi ke endpoint tertentu:

apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Enter fullscreen mode Exit fullscreen mode

Perintah daftar mengembalikan JSON terstruktur. Anda dapat memprosesnya dengan jq untuk menemukan ID ekspektasi:

apidog mock list --project <PROJECT_ID> | jq .
Enter fullscreen mode Exit fullscreen mode

Gunakan perintah berikut untuk membaca, memperbarui, atau menghapus ekspektasi:

apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Subperintah create dan update menerima file melalui --file. Validasi bentuk file sebelum mengirimkannya.

Validasi file ekspektasi sebelum menulis

Jangan menebak struktur JSON untuk ekspektasi mock. CLI menyediakan skema untuk setiap operasi tulis.

Ambil skema untuk membuat ekspektasi:

apidog cli-schema get mock-create
Enter fullscreen mode Exit fullscreen mode

Buat file mock.json sesuai skema, lalu validasi:

apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Jika valid, buat ekspektasi:

apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Untuk pembaruan, gunakan kunci skema mock-update:

apidog cli-schema validate mock-update --file ./mock.json
apidog mock update --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Alur yang aman adalah:

  1. Ambil skema dengan cli-schema get.
  2. Buat atau ubah mock.json.
  3. Validasi dengan cli-schema validate.
  4. Jalankan apidog mock create atau apidog mock update.

Jika validasi mengembalikan exit code selain nol, pipeline berhenti sebelum konfigurasi yang salah mencapai proyek Anda.

Setiap perintah juga mengembalikan JSON dengan blok agentHints.nextSteps, yang memberi tahu langkah berikutnya untuk manusia maupun agen pengodean AI. Untuk perintah lain, lihat panduan lengkap Apidog CLI.

Menghubungkannya ke CI

Kedua jalur dapat digunakan di CI karena perintah CLI menyediakan exit code dan output teks.

Contoh menjalankan Prism di latar belakang sebelum tes integrasi:

# Mulai Prism di latar belakang, lalu jalankan tes terhadapnya.
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

Untuk pipeline yang lebih aman, pastikan proses server selalu dihentikan:

npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

trap 'kill $PRISM_PID' EXIT
npm test
Enter fullscreen mode Exit fullscreen mode

Alur Apidog tidak memerlukan proses lokal karena mock di-hosting. Validasi dan terapkan ekspektasi sebelum tes berjalan:

# Pastikan ekspektasi valid, lalu terapkan ke proyek.
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Setelah itu, arahkan tes integrasi Anda ke URL mock yang di-hosting.

Tujuan utama mocking dari CLI adalah menghilangkan langkah klik manual. Tim spec-first, job CI, dan agen AI dapat membangun mock yang sama menggunakan perintah yang sama.

Hambatan umum

Mengharapkan apidog mock memulai server.

Itu tidak akan terjadi. Tidak ada apidog mock start, apidog mock serve, atau apidog mock ./file.yaml. Gunakan apidog import untuk mendapatkan mock yang di-hosting, lalu gunakan apidog mock untuk mengelola ekspektasi kustom. Jika memerlukan proses lokal dari file, gunakan Prism, Mockoon CLI, atau json-server.

Melewati validasi skema saat menulis ekspektasi.

apidog mock create dan apidog mock update menerima --file. Struktur yang salah dapat gagal atau membuat konfigurasi yang tidak diinginkan. Jalankan cli-schema get dan cli-schema validate terlebih dahulu.

Prism menghasilkan respons yang terlalu umum.

Kualitas mock Prism bergantung pada spesifikasi Anda. Jika respons tidak memiliki example dan skemanya terlalu samar, data yang dihasilkan juga akan samar. Tambahkan contoh respons ke OpenAPI untuk hasil yang lebih berguna.

Mengharapkan perilaku stateful dari alat stateless.

Prism dan mock kontrak Apidog tidak menyimpan hasil penulisan. Jika Anda membutuhkan POST yang kemudian dapat dibaca kembali melalui GET, gunakan json-server atau buat ekspektasi Apidog yang mengembalikan respons sesuai skenario tes.

Kesimpulan

Mocking dari CLI mengubah pekerjaan manual menjadi perintah yang dapat ditulis ke skrip, ditinjau dalam pull request, dan dijalankan oleh CI atau agen AI.

Pilih alat berdasarkan kebutuhan Anda:

  • Prism untuk mock OpenAPI berbasis kontrak.
  • Mockoon CLI untuk file data dan rute kustom tanpa GUI.
  • json-server untuk API REST stateful dari JSON.
  • Apidog untuk mock yang di-hosting dan terintegrasi dengan desain serta tes API.

Jika Anda membutuhkan server sementara dari satu file, jalur open-source biasanya cukup. Jika Anda ingin mock tetap sinkron dengan desain dan tes API dalam satu proyek, unduh Apidog, instal CLI, dan bangun mock tanpa menyentuh mouse.

Top comments (0)