Apa Itu Pengembangan API Berbasis Spesifikasi?

Sebagian besar bug API bukanlah kesalahan pengkodean. Melainkan kesalahan dalam kesepakatan. Frontend mengharapkan userId, backend mengirim user_id, dan tidak ada yang menyadarinya sampai QA. Pengembangan API yang mengutamakan spesifikasi (spec-first) memperbaiki masalah ini dengan menjadikan kontrak sebagai hal pertama yang Anda tulis, bukan hal terakhir yang Anda dokumentasikan.

Dalam panduan ini, Anda akan menulis spesifikasi OpenAPI kecil secara manual, lalu menggunakan satu file tersebut untuk menghasilkan mock, pengujian, dan dokumentasi sebelum ada kode server. Pendekatan yang sama dikenal dengan beberapa nama: pengembangan berbasis spesifikasi (spec-driven development), desain-pertama (design-first), atau kontrak-pertama (contract-first). Semuanya merujuk pada ide yang sama. Sepakati antarmuka terlebih dahulu, lalu bangunlah berdasarkan itu.

Apa itu pengembangan API spec-first

Pengembangan API spec-first berarti Anda membuat kontrak yang dapat dibaca mesin, biasanya dokumen OpenAPI, sebelum Anda mengimplementasikan endpoint. Kontrak tersebut menjelaskan setiap jalur, parameter, badan permintaan, bentuk respons, dan kode status. Setelah ada, itu menjadi sumber kebenaran bagi setiap orang yang berinteraksi dengan API.

Spesifikasi bukanlah dokumentasi yang tertinggal di belakang kode. Spesifikasi justru memimpin. Tim frontend membangun berdasarkan mock yang dihasilkan darinya. QA menulis pengujian berdasarkan itu. Backend mengimplementasikan untuk memenuhinya. Ketika ketiganya sepakat dengan file yang sama, integrasi berhenti menjadi tebak-tebakan.

Ini membalik urutan yang biasa. Dalam pengembangan code-first, Anda menulis handler dan kemudian mendeskripsikannya setelahnya, seringkali secara manual, dan seringkali kedaluwarsa dalam satu sprint. Dalam alur kerja design-first, deskripsi datang lebih dulu dan kode menjawabnya. Perubahan tunggal itu memindahkan sebagian besar masalah integrasi ke awal proyek, di mana mereka murah untuk diperbaiki.

Siklus hidup spec-first vs code-first

Kedua pendekatan menghasilkan endpoint yang sama. Perbedaannya terletak pada kapan masalah muncul dan siapa yang dapat memulai pekerjaan secara paralel.

Kolom kanan adalah hasilnya. Ketika kontrak ada lebih dulu, tiga tim berhenti saling menghalangi dan mulai membangun berdasarkan satu definisi bersama.

Contoh OpenAPI yang telah dikerjakan

Mari kita rancang endpoint kecil /users langkah demi langkah. Kita akan membangunnya secara bertahap agar setiap bagian jelas, lalu merakit file lengkapnya.

Mulai dengan header dokumen. Ini mendeklarasikan versi OpenAPI dan metadata dasar.

openapi: 3.0.3
info:
 title: Users API
 version: 1.0.0
servers:
 - url: https://api.example.com/v1

Selanjutnya, definisikan skema User di bawah components. Mendefinisikannya sekali memungkinkan Anda untuk mereferensikannya di mana saja, sehingga bentuknya tetap konsisten di seluruh permintaan dan respons.

components:
 schemas:
 User:
 type: object
 required: [id, email, createdAt]
 properties:
 id:
 type: string
 format: uuid
 email:
 type: string
 format: email
 name:
 type: string
 createdAt:
 type: string
 format: date-time

Sekarang tambahkan jalur GET /users. Ini mencantumkan pengguna dan mendukung parameter kueri limit. Perhatikan bagaimana respons menggunakan kembali skema User dengan $ref alih-alih mendefinisikannya ulang.

paths:
 /users:
 get:
 summary: List users
 operationId: listUsers
 parameters:
 - name: limit
 in: query
 schema:
 type: integer
 default: 20
 maximum: 100
 responses:
 "200":
 description: A list of users
 content:
 application/json:
 schema:
 type: array
 items:
 $ref: "#/components/schemas/User"

Tambahkan operasi POST /users untuk membuat pengguna. Badan permintaan mendefinisikan apa yang harus dikirim klien, dan respons 201 mengembalikan rekaman yang dibuat.

 post:
 summary: Create a user
 operationId: createUser
 requestBody:
 required: true
 content:
 application/json:
 schema:
 type: object
 required: [email]
 properties:
 email:
 type: string
 format: email
 name:
 type: string
 responses:
 "201":
 description: User created
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/User"
 "400":
 description: Invalid request body

Itu adalah kontrak yang lengkap dan valid. Ini menamai setiap bidang, menandai email sebagai wajib, membatasi limit hingga 100, dan mendeklarasikan respons sukses maupun error. Belum ada yang menulis sebaris pun kode server, tetapi kesepakatan sudah terkunci.

Hasilkan mock, pengujian, dan dokumentasi dari spesifikasi

Alasan untuk menulis spesifikasi terlebih dahulu adalah pengungkit. Satu file mendorong tiga artefak yang biasanya dibangun secara terpisah oleh tim.

Mock. Server mock membaca spesifikasi Anda dan mengembalikan contoh respons yang cocok dengan setiap skema. Petunjuk format: uuid dan format: email memungkinkan perkakas menghasilkan data sampel yang realistis. Frontend Anda memanggil GET /users dan mendapatkan array pengguna yang terstruktur dengan baik pada hari pertama, jauh sebelum handler yang sebenarnya ada. Ketika spesifikasi berubah, mock juga berubah.

Pengujian. Karena spesifikasi mendeklarasikan bidang yang wajib, tipe, dan kode status, itu berfungsi ganda sebagai oracle pengujian. Pengujian kontrak menyatakan bahwa respons sebenarnya untuk POST /users mengembalikan 201 dengan badan yang cocok dengan skema User, dan 400 ketika email hilang. Anda tidak mengarang asersi. Anda memeriksa apakah implementasi sesuai dengan apa yang telah Anda sepakati.

Dokumentasi. Dokumentasi referensi API dirender langsung dari spesifikasi. Setiap endpoint, parameter, dan contoh yang Anda lihat di dokumentasi berasal dari YAML yang sama. Tidak ada salinan kedua yang harus disinkronkan, sehingga dokumentasi tidak dapat menyimpang dari kontrak.

Ini juga yang membuat spec-first cocok dengan alur kerja API git-native: spesifikasi adalah file teks biasa, sehingga setiap perubahan pada kontrak muncul sebagai diff yang dapat ditinjau dalam pull request. Peninjau dapat melihat bahwa seseorang mengganti nama email atau menghilangkan bidang yang wajib sebelum dirilis.

Melakukannya di Apidog

Apidog mendukung ini secara menyeluruh melalui Mode Spec-First. Alih-alih memperlakukan file OpenAPI sebagai ekspor, ia memperlakukan file tersebut sebagai proyek. Anda mengedit YAML secara langsung dan seluruh ruang kerja akan mengikutinya.

Anda menulis atau menempelkan spesifikasi /users ke dalam editor. Apidog menguraikannya dan segera membuat server mock untuk kedua operasi, sehingga frontend Anda dapat mulai memanggilnya. Dokumentasi yang dihasilkan diperbarui saat Anda mengetik. Ketika Anda siap untuk memverifikasi implementasi, Anda menjalankan operasi spesifikasi sebagai kasus uji terhadap backend Anda yang sebenarnya dan mengonfirmasi bahwa respons sesuai dengan skema.

Bagian yang menjaga integritas ini adalah sinkronisasi Git dua arah. Spesifikasi Anda berada dalam repositori, dan perubahan mengalir di kedua arah. Edit YAML di editor Anda dan push, dan Apidog akan mengambilnya. Edit di Apidog, dan perubahan akan muncul sebagai commit yang dapat ditinjau oleh tim Anda. Kontrak tidak pernah berada di dua tempat sekaligus. Jika Anda ingin perbandingan yang lebih mendalam tentang posisi ini dibandingkan dengan pendekatan design-first murni, lihat spec-first vs design-first di Apidog.

Daftar periksa spec-first

Gunakan ini sebelum Anda menyatakan spesifikasi siap untuk dibangun berdasarkan:

• Spesifikasi tervalidasi terhadap skema OpenAPI tanpa kesalahan.
• Setiap endpoint mendeklarasikan respons suksesnya dan setidaknya satu respons error.
• Bentuk yang dibagikan berada di components/schemas dan direferensikan dengan $ref, tidak disalin.
• Bidang wajib ditandai required, dan format (uuid, email, date-time) diatur di mana pun berlaku.
• File spesifikasi di-commit ke kontrol versi dan ditinjau dalam pull request.
• Server mock berjalan dari spesifikasi, dan frontend dapat mengaksesnya.
• Pengujian kontrak memeriksa respons sebenarnya terhadap skema yang dideklarasikan.
• Dokumentasi yang diterbitkan dirender dari file yang sama, tanpa salinan yang dikelola secara manual.

Jika setiap kotak telah dicentang, tim Anda dapat membangun secara paralel berdasarkan satu kesepakatan, bukan tiga tebakan.

Pertanyaan Umum (FAQ)

Apakah pengembangan API spec-first sama dengan design-first?

Sebagian besar ya. “Design-first” (desain-pertama) dan “contract-first” (kontrak-pertama) menggambarkan prinsip yang sama: tulis antarmuka sebelum implementasi. “Spec-first” (spesifikasi-pertama) adalah nama yang paling harfiah karena file spesifikasi OpenAPI adalah artefak konkret yang Anda mulai. Dalam praktiknya, istilah-istilah ini digunakan secara bergantian.

Apakah saya harus menulis YAML secara manual?

Tidak. Anda dapat membuat spesifikasi di editor visual dan membiarkannya menghasilkan YAML, atau menulis YAML secara langsung jika Anda lebih suka. Intinya bukan format yang Anda ketik, melainkan bahwa kontrak itu ada dan disepakati sebelum kode. Banyak tim menggabungkan keduanya, membuat draf secara visual dan menyempurnakannya dalam YAML selama peninjauan.

Bagaimana cara mencegah spesifikasi dan kode menyimpang?

Jadikan spesifikasi sebagai sumber kebenaran dan terapkan. Simpan spesifikasi di Git agar perubahan ditinjau sebagai diff. Jalankan pengujian kontrak di CI sehingga build gagal ketika respons tidak lagi cocok dengan skema. Dengan sinkronisasi dua arah, pengeditan di kedua tempat tetap rekonsiliasi, yang menghilangkan penyebab paling umum dari penyimpangan.

Pengembangan API spec-first adalah perubahan kecil dalam urutan dengan perubahan besar dalam hasil. Tulis kontraknya, sepakati, lalu bangunlah berdasarkan itu. Jika Anda ingin melihat alur lengkapnya, buka Mode Spec-First di Apidog dan arahkan ke repositori Anda.