Platform API untuk Alur Kerja API Design-First

Intinya

Pendekatan desain-pertama berarti spesifikasi API ditulis sebelum kode implementasi. Spesifikasi menjadi sumber kebenaran untuk mock, dokumentasi, pengujian, dan stub klien. Dengan platform yang mendukung alur kerja ini end-to-end, tim tidak perlu terus-menerus menyinkronkan kode dan dokumentasi secara manual.

Coba Apidog hari ini

Apidog

Coba Apidog gratis

Pengantar

Banyak pengembang memulai dengan pendekatan code-first:

1. Tulis route.
2. Tambahkan anotasi.
3. Jalankan generator dokumentasi.
4. Bagikan dokumentasi ke tim lain.

Pendekatan ini bekerja sampai dokumentasi mulai tidak sinkron dengan implementasi.

Contoh masalah umum:

// Dokumentasi mengatakan:
["admin", "editor"]

// Respons aktual:
[
  { "value": "admin" },
  { "value": "editor" }
]

Masalah seperti ini biasanya baru terlihat saat integrasi frontend-backend. Pendekatan desain-pertama membalik alurnya: kontrak API didefinisikan dulu, lalu implementasi mengikuti kontrak tersebut.

Dengan desain-pertama:

• Spesifikasi adalah sumber kebenaran.
• Mock dibuat dari spesifikasi.
• Dokumentasi dirender dari spesifikasi.
• Pengujian memvalidasi implementasi terhadap spesifikasi.
• Perubahan API ditinjau sebelum kode berubah.

Namun, desain-pertama hanya praktis jika alatnya cepat digunakan. Jika menulis spesifikasi membutuhkan waktu jauh lebih lama daripada menulis handler, tim akan kembali ke code-first.

---

Apa Arti Desain-Pertama dalam Praktik

Desain-pertama bukan sekadar menulis file OpenAPI. Ini adalah alur kerja pengembangan API berbasis kontrak.

1. Sebelum Menulis Kode

Definisikan API sebagai spesifikasi OpenAPI.

Minimal, spesifikasi harus mencakup:

• Path endpoint dan metode HTTP
• Parameter path, query, dan header
• Request body untuk POST, PUT, atau PATCH
• Respons untuk status umum seperti 200, 400, 401, 422, dan 500
• Skema error
• Aturan autentikasi
• Deskripsi field dan contoh payload

Contoh potongan OpenAPI sederhana:

openapi: 3.0.3
info:
  title: "User API"
  version: 1.0.0

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: "User ditemukan"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfile"
        "404":
          description: "User tidak ditemukan"

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: integer
          example: 1
        email:
          type: string
          format: email
          example: [e-mail]

Keputusan penting seperti struktur data, format error, naming, dan pagination sebaiknya diselesaikan di tahap ini.

2. Selama Pengembangan

Setelah spesifikasi tersedia:

• Frontend menggunakan mock API.
• Backend mengimplementasikan endpoint berdasarkan spesifikasi.
• QA dapat mulai menyusun skenario pengujian.
• Dokumentasi sudah dapat dibaca sebelum implementasi selesai.

Frontend tidak perlu menunggu backend selesai hanya untuk mulai integrasi awal.

3. Setelah Implementasi

Jalankan validasi otomatis untuk memastikan respons aktual sesuai spesifikasi.

Yang perlu dicek:

• Status code
• Struktur JSON
• Tipe data field
• Field wajib
• Format seperti email, date-time, atau uuid
• Skema error

Jika implementasi menyimpang dari kontrak, pengujian harus gagal.

4. Ketika Persyaratan Berubah

Jangan langsung mengubah handler backend.

Urutan yang lebih aman:

1. Perbarui spesifikasi.
2. Tinjau perubahan dengan frontend, backend, dan pemangku kepentingan terkait.
3. Perbarui mock.
4. Sesuaikan implementasi.
5. Jalankan pengujian validasi skema.

Dengan begitu, perubahan API tetap eksplisit dan terdokumentasi.

---

Apa yang Dibutuhkan Platform Desain-Pertama

Tidak semua alat API cocok untuk desain-pertama. Platform yang baik harus membuat spesifikasi mudah ditulis, ditinjau, dan digunakan oleh tim.

Editor API Visual

Menulis YAML mentah bisa lambat dan rawan salah indentasi. Editor visual membantu tim fokus pada struktur API.

Editor yang baik harus mendukung:

• Path dan method
• Parameter
• Request body
• Response schema
• Reusable schema atau component
• Validasi real-time
• Ekspor OpenAPI standar

Validasi OpenAPI

Spesifikasi harus valid sebelum digunakan untuk mock, dokumentasi, atau generator kode.

Validasi inline membantu menangkap masalah seperti:

• $ref yang salah
• Field wajib yang tidak lengkap
• Format schema yang tidak valid
• Status code tanpa response schema
• Parameter path yang tidak didefinisikan

Mock Otomatis dari Spesifikasi

Alur ideal:

1. Definisikan endpoint.
2. Simpan spesifikasi.
3. Mock URL langsung tersedia.
4. Frontend mulai menggunakan mock.

Mock harus mengikuti schema, termasuk:

• Tipe data
• Format field
• Enum
• Array
• Object bertingkat
• $ref component

Pratinjau Dokumentasi

Spesifikasi harus bisa dirender menjadi dokumentasi yang mudah dibaca.

Gunakan pratinjau dokumentasi untuk mengecek:

• Apakah nama field jelas?
• Apakah deskripsi cukup membantu?
• Apakah contoh payload realistis?
• Apakah format error konsisten?
• Apakah endpoint mudah dipahami oleh tim non-backend?

Alur Review Tim

Perubahan spesifikasi sebaiknya diperlakukan seperti perubahan kode.

Praktik yang disarankan:

• Komentar pada endpoint atau field tertentu
• Review sebelum implementasi
• Riwayat perubahan
• Persetujuan untuk perubahan breaking
• Diskusi asinkron di dalam platform

Ekspor OpenAPI Standar

Spesifikasi harus portabel.

Pastikan spesifikasi bisa diekspor sebagai OpenAPI 3.x agar dapat digunakan dengan:

• Code generator
• API gateway
• Test framework
• Dokumentasi eksternal
• Server stub generator

Contoh penggunaan dengan openapi-generator:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./generated-server

---

Apidog sebagai Platform Desain-Pertama

Apidog dibangun dengan spesifikasi API sebagai artefak utama. Desain API, mock server, dokumentasi, dan pengujian terhubung ke definisi API yang sama.

Editor OpenAPI Visual

Di Apidog, endpoint didefinisikan melalui form terstruktur:

• Path
• Method
• Parameter
• Request body
• Response body
• Schema
• Deskripsi
• Aturan validasi
• Anotasi mock

Anda tidak harus menulis YAML secara manual. Namun, jika diperlukan, Apidog juga menyediakan tampilan mentah untuk melihat atau mengedit representasi YAML atau JSON.

Perubahan pada editor visual dan tampilan mentah disinkronkan.

Gunakan Component untuk Schema Bersama

Untuk menghindari duplikasi, definisikan schema yang sering dipakai sebagai component.

Contoh schema reusable:

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: USER_NOT_FOUND
        message:
          type: string
          example: User tidak ditemukan

    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 100

Lalu referensikan dengan $ref:

responses:
  "400":
    description: Bad request
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ErrorResponse"

Keuntungannya: ubah schema sekali, semua endpoint yang memakai schema tersebut ikut konsisten.

Pratinjau Dokumentasi Real-Time

Saat endpoint dirancang, dokumentasi dapat dipratinjau.

Gunakan pratinjau ini untuk memvalidasi:

• Deskripsi endpoint
• Tabel schema
• Tipe field
• Constraint
• Contoh request dan response

Bagikan tautan dokumentasi ke product manager, frontend lead, atau QA untuk review sebelum implementasi dimulai.

Smart Mock: Dari Spesifikasi ke Mock API

Setelah endpoint disimpan di Apidog, mock server dapat digunakan.

Mock menghasilkan data berdasarkan schema, misalnya:

• format: email menghasilkan email valid
• minimum dan maximum menghasilkan angka dalam rentang
• enum menghasilkan salah satu nilai enum
• Object dan array bertingkat mengikuti struktur schema
• $ref component diselesaikan dengan benar

Contoh schema:

UserProfile:
  type: object
  properties:
    id:
      type: integer
      minimum: 1
    email:
      type: string
      format: email
    role:
      type: string
      enum:
        - admin
        - editor
        - viewer

Mock dapat menghasilkan respons yang sesuai dengan struktur tersebut tanpa backend selesai lebih dulu.

Anda juga dapat membuat aturan mock khusus untuk skenario tertentu, misalnya:

• Kembalikan 404 jika path parameter bernilai 0
• Kembalikan payload tertentu untuk query tertentu
• Simulasikan error response untuk kebutuhan UI state

Review Tim dan Riwayat Perubahan

Perubahan spesifikasi di Apidog dapat dilihat oleh anggota workspace.

Gunakan fitur review untuk:

• Memberi komentar pada endpoint
• Mendiskusikan field tertentu
• Melihat siapa yang mengubah apa
• Melacak perubahan kontrak API

Untuk alur desain-pertama, ini membantu menjaga perubahan API tetap transparan.

---

Desain-Pertama vs Code-First: Kompromi Sebenarnya

Desain-pertama bukan selalu pilihan terbaik untuk semua kasus. Berikut perbandingan praktisnya.

Keunggulan Desain-Pertama

• Frontend dan backend bisa bekerja paralel.
• Dokumentasi lebih akurat karena berasal dari spesifikasi.
• Masalah integrasi muncul lebih awal.
• Kontrak API eksplisit dan bisa diuji.
• Perubahan API melewati proses review.
• Mock tersedia sebelum implementasi selesai.

Kekurangan Desain-Pertama

• Perlu waktu awal untuk mendefinisikan spesifikasi.
• Tim perlu mempelajari alat spesifikasi.
• Perlu disiplin agar implementasi tetap sesuai kontrak.
• Spesifikasi yang terlalu dini bisa mengunci keputusan sebelum domain cukup dipahami.

Keunggulan Code-First

• Cepat untuk prototipe kecil.
• Cocok untuk eksperimen solo.
• Tidak perlu mempelajari alat spesifikasi.
• Lebih sederhana saat API belum stabil.

Kekurangan Code-First

• Dokumentasi mudah tidak sinkron.
• Frontend sering menunggu backend.
• Kontrak API implisit.
• Breaking change lebih sulit dideteksi.
• Refactor API membutuhkan pembaruan dokumentasi manual.

Untuk tim yang melibatkan lebih dari satu engineer, terutama jika ada koordinasi frontend-backend, desain-pertama biasanya memberi hasil lebih konsisten.

---

Alat yang Mendukung Alur Kerja Desain-Pertama

Apidog

Apidog menyediakan editor visual, mocking instan, dokumentasi, pengujian, dan review tim dalam satu platform. Mocking dari spesifikasi menjadi salah satu pembeda utamanya.

Stoplight Studio

Stoplight Studio kuat sebagai editor OpenAPI dan mendukung linting Spectral untuk konsistensi style. Cocok untuk organisasi yang fokus pada governance spesifikasi.

SwaggerHub

SwaggerHub adalah platform OpenAPI yang matang dan banyak digunakan di perusahaan. Cocok untuk organisasi yang sudah bergantung pada ekosistem Swagger.

Postman dengan API Builder

Postman memiliki fitur desain API untuk menghasilkan spesifikasi OpenAPI. Namun, alur antara desain API dan collection dapat terasa terpisah. Mock server biasanya membutuhkan pengaturan manual dari collection.

Insomnia dengan Mode Dokumen

Insomnia mendukung pengeditan spesifikasi OpenAPI dan mock dasar. Cocok untuk pengembang solo yang ingin opsi ringan.

---

Menyiapkan Alur Kerja Desain-Pertama di Apidog

Berikut alur implementasi yang bisa langsung diterapkan.

Langkah 1: Mulai dari Spesifikasi, Bukan Collection

Buat proyek baru, lalu masuk ke tab desain.

Sebelum mengirim request pertama, definisikan minimal:

• Endpoint path
• HTTP method
• Request parameter
• Response schema
• Error response

Contoh checklist endpoint:

GET /users/{id}

[ ] Path parameter: id
[ ] Response 200: UserProfile
[ ] Response 404: ErrorResponse
[ ] Auth requirement
[ ] Example response
[ ] Field description

Langkah 2: Definisikan Component Bersama

Sebelum membuat banyak endpoint, buat schema reusable untuk pola umum.

Contoh component yang sebaiknya dibuat sejak awal:

• ErrorResponse
• Pagination
• UserProfile
• CreatedResponse
• ValidationError
• Meta
• PageInfo

Ini mencegah setiap endpoint memiliki format error atau pagination yang berbeda.

Langkah 3: Buat Endpoint dan Simpan Mock URL

Setelah endpoint disimpan, ambil mock URL dari Apidog dan bagikan ke frontend.

Frontend bisa langsung menggunakannya seperti API biasa:

const response = await fetch("https://mock-url.example/users/1");
const user = await response.json();

console.log(user.email);

Dengan cara ini, UI dapat dibangun sebelum backend selesai.

Langkah 4: Review Dokumentasi Sebelum Implementasi

Buka pratinjau dokumentasi dan cek apakah API sudah cukup jelas.

Gunakan pertanyaan berikut:

• Apakah nama endpoint mudah dipahami?
• Apakah deskripsi field cukup spesifik?
• Apakah response error konsisten?
• Apakah contoh payload membantu?
• Apakah frontend bisa membangun UI dari kontrak ini?

Jika dokumentasi membingungkan, perbaiki spesifikasi sebelum menulis kode.

Langkah 5: Kunci Spesifikasi untuk Sprint

Setelah review selesai, perlakukan spesifikasi sebagai kontrak sprint.

Jika ada perubahan selama implementasi:

1. Update spesifikasi.
2. Review perubahan.
3. Update mock.
4. Update implementasi.
5. Jalankan pengujian.

Hindari perubahan diam-diam langsung di backend.

Langkah 6: Validasi Implementasi dengan Pengujian

Setelah backend tersedia, jalankan pengujian untuk memastikan respons aktual sesuai schema.

Validasi yang perlu dilakukan:

• Status code sesuai
• Body sesuai schema
• Field wajib tersedia
• Tipe data benar
• Error response konsisten

Jika menggunakan CI, jadikan validasi ini bagian dari pipeline agar kontrak API tidak rusak tanpa terdeteksi.

---

Pertanyaan Umum

Apakah desain-pertama hanya untuk REST API?

Tidak. Prinsip desain-pertama berlaku untuk protokol apa pun yang memiliki kontrak eksplisit.

Contohnya:

• REST dengan OpenAPI
• GraphQL dengan schema-first
• gRPC dengan protobuf
• AsyncAPI untuk sistem event-driven

Apidog mendukung desain REST dan GraphQL. Untuk gRPC, file proto memiliki tujuan kontrak-pertama yang sama.

Apakah semua endpoint harus didefinisikan sebelum pengembangan dimulai?

Tidak.

Anda bisa mengadopsi desain-pertama per fitur. Definisikan spesifikasi untuk fitur yang akan dibangun, walaupun bagian lain dari codebase masih code-first.

Adopsi bertahap lebih realistis daripada migrasi besar sekaligus.

Bagaimana desain-pertama bekerja dalam sprint agile?

Di awal sprint, tim mendefinisikan kontrak API untuk fitur sprint tersebut.

Alur yang umum:

1. Product dan engineering menyepakati kebutuhan data.
2. Backend membuat spesifikasi.
3. Frontend dan QA memberi review.
4. Mock dibagikan.
5. Frontend dan backend bekerja paralel.
6. Implementasi divalidasi terhadap spesifikasi.

Review spesifikasi menjadi bagian dari planning atau refinement.

Bagaimana jika implementasi perlu menyimpang dari spesifikasi awal?

Itu normal.

Yang penting adalah urutannya:

1. Update spesifikasi.
2. Dapatkan persetujuan dari pihak terkait, terutama frontend.
3. Update implementasi.
4. Jalankan validasi ulang.

Dengan begitu, spesifikasi tetap menjadi sumber kebenaran.

Bisakah stub server dibuat dari ekspor OpenAPI Apidog?

Ya. Ekspor spesifikasi dari Apidog sebagai OpenAPI 3.x, lalu gunakan generator kode standar.

Contoh:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-stub

openapi-generator mendukung banyak bahasa dan framework server.

Bagaimana menangani versi spesifikasi?

Untuk perubahan kecil, gunakan riwayat perubahan di proyek.

Untuk versi besar yang berjalan paralel, seperti v1 dan v2, gunakan proyek atau cabang terpisah agar kontrak masing-masing versi tetap jelas.

---

Kesimpulan

Desain-pertama membutuhkan disiplin di awal, tetapi mengurangi biaya integrasi di akhir.

Alur yang efektif adalah:

1. Tulis spesifikasi.
2. Review kontrak.
3. Jalankan mock.
4. Bangun frontend dan backend secara paralel.
5. Validasi implementasi terhadap spesifikasi.
6. Kelola perubahan melalui review.

Platform yang baik harus membuat langkah pertama semudah mungkin. Jika menulis spesifikasi terasa berat, tim akan melewatkannya. Dengan editor visual, mocking instan, dokumentasi, dan pengujian dalam satu alur, Apidog membuat desain-pertama lebih praktis untuk tim API sehari-hari.