Generator denah rumah berbasis model dapat membutuhkan waktu cukup lama untuk memproses permintaan, sehingga kontrak API-nya perlu menangani lebih dari sekadar input dan hasil. Rancang API yang memvalidasi kebutuhan ruang serta batasan bangunan, mengembalikan ID job, dan menyediakan cara aman untuk memeriksa status serta mengambil hasil.
Pola berikut cocok untuk layanan yang menghasilkan denah secara asinkron. Ini panduan desain integrasi, bukan klaim tentang implementasi internal produk tertentu.
1. Tetapkan kontrak input yang eksplisit
Hindari menerima seluruh kebutuhan sebagai teks bebas. Teks dapat menjadi masukan tambahan, tetapi field terstruktur lebih mudah divalidasi, didokumentasikan, dan diproses secara konsisten. Tetapkan satuan, nilai yang diwajibkan, rentang yang diizinkan, dan perilaku ketika batasan saling bertentangan.
Contoh berikut menggunakan meter untuk ukuran dan mencantumkan versi skema secara eksplisit:
{
"schema_version": "1.0",
"requirements": {
"rooms": [
{ "type": "bedroom", "count": 3 },
{ "type": "bathroom", "count": 2 },
{ "type": "kitchen", "count": 1 },
{ "type": "living_room", "count": 1 }
],
"total_area_m2": { "min": 90, "max": 120 },
"floors": 1
},
"site": {
"plot_width_m": 10,
"plot_length_m": 20,
"setbacks_m": {
"front": 3,
"back": 2,
"left": 1,
"right": 1
}
},
"preferences": {
"style": "modern",
"notes": "Utamakan ventilasi alami."
}
}Gunakan enum dengan nilai yang terdokumentasi untuk field seperti type dan style. Tolak nilai yang tidak dikenal, kecuali kontrak memang mendefinisikan cara mengabaikannya. Validasi juga aturan lintas-field: luas minimum tidak boleh melebihi luas maksimum, jumlah ruang harus positif, dan luas tapak harus cukup untuk batas sempadan yang diberikan.
Bedakan batasan keras dari preferensi lunak. Misalnya, batas sempadan bangunan adalah batas keras; preferensi gaya dapat menjadi masukan lunak. Jika generator tidak dapat memenuhi semua batasan keras, kembalikan error validasi atau status kegagalan yang menjelaskan konflik—jangan diam-diam mengubah persyaratan.
2. Versikan skema dan definisikan hasil
Field schema_version membantu server memilih aturan validasi yang tepat dan memberi jalur migrasi ketika format berubah. Jangan menggunakan satu nomor versi untuk menyamarkan perubahan yang tidak kompatibel. Perubahan seperti mengganti nama field, mengubah satuan, atau mengubah tipe data perlu diperlakukan sebagai perubahan kontrak.
Tentukan terlebih dahulu bentuk hasil yang bisa dijanjikan. Jika hasil berupa denah terstruktur, dokumentasikan unit koordinat, sistem sumbu, tipe geometri, dan cara mengaitkan elemen dengan ruang. Jika hasil berupa file, berikan URL unduhan sementara beserta waktu kedaluwarsanya. Jangan menganggap URL unduhan berlaku permanen.
Respons hasil dapat menyertakan metadata yang stabil, seperti luas terhitung dan daftar peringatan. Dokumentasikan apakah angka tersebut berasal dari batasan pengguna atau hasil perhitungan. Jangan menjanjikan format keluaran yang belum benar-benar didukung.
3. Gunakan operasi asinkron untuk pembuatan denah
Jangan menahan koneksi HTTP terbuka selama proses generasi yang durasinya tidak pasti. Pisahkan penerimaan permintaan dari pemrosesan: server memvalidasi input, membuat job, lalu segera mengembalikan ID job. Klien memeriksa status melalui endpoint terpisah.
- Kirim permintaan. Klien mengirim
POST /v1/floor-plansdengan token autentikasi danIdempotency-Key. - Terima job. Server mengembalikan
202 Accepteddengan ID job dan URL status. - Periksa status. Klien melakukan
GETke URL status, dengan jeda antar-pemeriksaan yang meningkat jika job masih berjalan. - Ambil hasil. Setelah status menjadi
succeeded, klien meminta hasil atau mengikuti URL hasil yang diberikan. - Tangani kegagalan. Jika status menjadi
failed, klien membaca kode error dan memutuskan apakah permintaan perlu diperbaiki atau dicoba ulang.
Contoh permintaan dan respons awal:
POST /v1/floor-plans
Authorization: Bearer <access-token>
Idempotency-Key: 4f2cf4de-45f4-4bb8-8a97-08653445b352
Content-Type: application/json
{
"schema_version": "1.0",
"requirements": {
"rooms": [{ "type": "bedroom", "count": 2 }],
"total_area_m2": { "min": 70, "max": 90 },
"floors": 1
},
"site": {
"plot_width_m": 8,
"plot_length_m": 16,
"setbacks_m": {
"front": 2,
"back": 2,
"left": 1,
"right": 1
}
}
}HTTP/1.1 202 Accepted
Content-Type: application/json
{
"job_id": "job_8b1d2a",
"status": "queued",
"status_url": "/v1/floor-plans/jobs/job_8b1d2a"
}Representasikan status dengan nilai yang terbatas dan terdokumentasi, misalnya queued, running, succeeded, dan failed. Respons pemeriksaan status sebaiknya menyertakan status, waktu pembaruan, dan tautan hasil atau error jika tersedia. Jangan menyamakan status job dengan status HTTP: permintaan untuk membaca job yang valid dapat menghasilkan HTTP 200 meskipun job masih running.
4. Cegah job dan biaya duplikat
Klien dapat mengalami timeout setelah server menerima permintaan tetapi sebelum respons sampai. Jika klien mengirim ulang sebagai permintaan baru, server bisa membuat dua job dan menimbulkan biaya ganda. Idempotency key mengatasi ketidakpastian ini.
Untuk permintaan pertama, server menyimpan pasangan identitas pemanggil dan idempotency key, hash payload, serta hasil penerimaan atau ID job. Jika key yang sama dikirim ulang dengan payload yang sama, kembalikan job atau respons yang sama. Jika key yang sama dipakai untuk payload berbeda, tolak permintaan, misalnya dengan 409 Conflict. Batasi cakupan key berdasarkan akun atau tenant, dan dokumentasikan masa retensinya.
Penyimpanan key dan pembuatan job harus terlindungi dari kondisi balapan: dua permintaan serentak dengan key sama tidak boleh membuat dua job. Terapkan keunikan di penyimpanan dan buat pencatatan idempotensi serta job secara atomik sejauh arsitektur memungkinkan. Jika job diteruskan ke antrean, pastikan kegagalan di antara penyimpanan job dan pengiriman pesan dapat dipulihkan, misalnya dengan pola transactional outbox.
Idempotensi tidak menghilangkan kebutuhan mengendalikan biaya. Terapkan batas kuota, pembatasan laju, batas ukuran permintaan, dan aturan retensi hasil. Jangan mengandalkan deduplikasi berdasarkan kesamaan payload saja: pengguna dapat sengaja meminta generasi baru dengan input identik.
5. Autentikasi, timeout, dan error
Autentikasi dan otorisasi
Gunakan autentikasi yang sesuai dengan jenis klien, seperti token akses untuk integrasi server-ke-server. Batasi setiap token pada akun atau tenant tertentu, dan periksa otorisasi saat membaca status maupun hasil job—mengetahui ID job tidak boleh menjadi satu-satunya syarat akses. Hindari mencatat token atau data sensitif dalam log.
Timeout dan percobaan ulang
Tetapkan timeout klien untuk pengiriman permintaan, pemeriksaan status, dan pengambilan hasil. Timeout pada klien tidak membuktikan bahwa server gagal memproses permintaan. Untuk pengiriman ulang, gunakan idempotency key yang sama. Untuk pemeriksaan status, percobaan ulang biasanya lebih aman karena operasinya hanya membaca data, tetapi tetap gunakan jeda dan batas percobaan agar tidak membebani layanan.
Jangan mengulang error validasi atau autentikasi tanpa perubahan. Untuk error sementara seperti gangguan layanan atau pembatasan laju, respons dapat menyertakan petunjuk waktu percobaan ulang, misalnya melalui header Retry-After jika didukung. Dokumentasikan kebijakan tersebut; klien tidak boleh mengasumsikan nilainya selalu ada.
Format error yang dapat ditindaklanjuti
Gunakan bentuk error yang konsisten dan kode mesin yang stabil. Pesan untuk manusia membantu debugging, tetapi logika klien sebaiknya bergantung pada code, bukan mencocokkan teks pesan.
{
"error": {
"code": "INVALID_CONSTRAINTS",
"message": "Luas tapak yang tersisa tidak cukup untuk batas sempadan.",
"details": [
{
"field": "site.setbacks_m",
"reason": "required_area_exceeds_plot_area"
}
],
"request_id": "req_31ac"
}
}Gunakan status HTTP yang sesuai untuk kegagalan pada request HTTP, seperti input tidak valid, autentikasi gagal, konflik idempotensi, atau pembatasan laju. Untuk kegagalan saat job berjalan, simpan error pada representasi job agar klien dapat melihatnya melalui endpoint status. Sertakan ID request untuk membantu penelusuran log tanpa membocorkan detail internal.
6. Checklist implementasi dan debugging
- Dokumentasikan satuan, enum, field wajib, batas nilai, dan aturan lintas-field.
- Validasi payload di batas API sebelum membuat job atau memicu proses berbiaya.
- Uji permintaan berulang dengan key dan payload sama; pastikan ID job tetap sama.
- Uji key sama dengan payload berbeda; pastikan server menolaknya tanpa membuat job kedua.
- Simulasikan timeout setelah server menerima POST; kirim ulang dengan key yang sama dan pastikan job dapat ditemukan.
- Uji akses status dan hasil lintas akun; pastikan data tidak dapat dibaca oleh pemanggil yang tidak berwenang.
- Pastikan status akhir tidak berubah kembali menjadi status berjalan dan hasil hanya tersedia sesuai aturan akses.
- Log ID request dan ID job untuk korelasi, tetapi hindari mencatat kredensial atau seluruh payload jika memuat data sensitif.
Kontrak yang baik membuat penerimaan permintaan, pemrosesan job, dan pengambilan hasil menjadi tahapan terpisah dengan aturan yang dapat diuji. Kombinasi skema eksplisit, status job yang stabil, serta idempotensi pada batas penerimaan memberi klien cara pulih dari timeout tanpa membuat job atau biaya duplikat.
Komentar
0 komentar
Masuk ke akun kamu untuk ikut berkomentar.
Belum ada komentar
Jadilah yang pertama ikut berdiskusi!