18.3 API dan Contract sebagai Perjanjian
Setelah Anda membagi sistem menjadi modul-modul yang terpisah, pertanyaan berikutnya adalah: bagaimana modul-modul ini berbicara satu sama lain? Tanpa jawaban yang jelas, modularitas hanya akan menjadi ilusi. Setiap modul tetap bisa saling memengaruhi secara tidak terduga, dan AI yang Anda libatkan untuk membantu pengembangan akan kesulitan memahami batasan masing-masing bagian.
Bayangkan Anda bekerja di sebuah perusahaan e-commerce. Tim produk ingin menambahkan fitur rekomendasi yang menggunakan AI untuk menyarankan barang berdasarkan riwayat pembelian. Modul rekomendasi ini perlu mengambil data dari modul order, modul katalog, dan modul user profile. Jika tidak ada kesepakatan yang jelas tentang bagaimana data diambil dan dalam format apa, maka setiap kali salah satu modul berubah, modul rekomendasi Anda bisa rusak. AI yang membantu menulis kode rekomendasi pun akan bingung: data mana yang aman dipakai, mana yang tidak, dan bagaimana cara mengaksesnya tanpa merusak sistem lain.
Di sinilah API dan contract berperan sebagai perjanjian. API — antarmuka pemrograman aplikasi — adalah pintu resmi yang disediakan oleh sebuah modul untuk diakses oleh modul lain. Contract adalah isi perjanjiannya: format data yang dikirim, struktur respons yang diharapkan, batasan jumlah panggilan, dan aturan-aturan lain yang harus dipatuhi kedua belah pihak. Selama kedua modul setuju pada contract yang sama, mereka bisa berkembang secara independen tanpa saling mengganggu.
Yang membuat contract ini penting di era AI adalah kemampuannya untuk membatasi konteks. Ketika Anda meminta AI untuk menulis kode yang memanggil modul order, AI tidak perlu memahami seluruh logika bisnis di dalam modul order. Ia hanya perlu tahu: “Ini API-nya, ini contract-nya, ini yang boleh dan tidak boleh dilakukan.” Dengan kata lain, contract menjadi pagar yang membuat AI tetap produktif tanpa perlu menjadi ahli seluruh sistem.
Diagram berikut memperlihatkan alur komunikasi antara dua modul melalui API dengan contract sebagai perjanjian.
Contoh konkret: modul order memiliki API getOrderHistory(userId) yang mengembalikan array objek dengan field orderId, date, totalAmount, dan status. Contract ini sudah terdokumentasi dan diuji. Ketika AI diminta membuat fitur yang menampilkan riwayat belanja, ia tinggal membaca contract itu, menulis kode pemanggilan, dan yakin bahwa hasilnya sesuai ekspektasi. Jika suatu hari modul order berubah, selama contractnya tetap sama — misalnya format respons tidak berubah — maka kode yang ditulis AI tetap berfungsi.
Berikut adalah contoh contract API dalam format OpenAPI 3.0 yang mendefinisikan endpoint, skema request/response, dan batasan akses untuk modul order.
openapi: 3.0.0
info:
title: Modul Order API
version: 1.0.0
paths:
/getOrderHistory:
get:
parameters:
- name: userId
in: query
required: true
schema:
type: string
responses:
'200':
description: Daftar riwayat pesanan
content:
application/json:
schema:
type: array
items:
type: object
properties:
orderId:
type: string
date:
type: string
format: date
totalAmount:
type: number
status:
type: string
enum: [pending, shipped, delivered, cancelled]
required: [orderId, date, totalAmount, status]
x-rate-limit:
maxRequestsPerMinute: 100
Dengan contract seperti ini, AI cukup membaca spesifikasi di atas untuk mengetahui endpoint, parameter, format respons, dan batasan akses tanpa harus menyelami kode internal modul order.
Namun, contract tidak boleh berubah seenaknya. Di sinilah backward compatibility menjadi penting. Jika modul order ingin menambahkan field baru ke dalam respons, itu aman karena kode lama tetap bisa membaca field yang sudah ada. Tapi jika modul order menghapus field status, semua pemanggil yang bergantung pada field itu akan rusak. Untuk mencegah hal ini, tim perlu menerapkan contract testing: pengujian otomatis yang memastikan bahwa setiap perubahan pada API tidak melanggar perjanjian yang sudah disepakati.
Dengan API dan contract yang jelas, AI bisa bekerja seperti kontraktor yang tahu persis ruang lingkup pekerjaannya. Ia tidak perlu bertanya ke mana-mana, tidak perlu menebak-nebak, dan tidak perlu akses ke seluruh sistem. Cukup baca contract, kerjakan tugas, dan serahkan hasilnya.
Tapi API dan contract hanya mengatur bagaimana modul berbicara satu sama lain. Pertanyaan berikutnya yang sama pentingnya adalah: bagaimana dengan data dan state yang mengalir di antara modul-modul ini? Siapa yang memiliki data? Siapa yang boleh mengubahnya? Dan bagaimana AI bisa memodifikasi data tanpa membuat kekacauan?
