Modul 04Penggal 1 · Asas4 item poster

API dan Kontrak

Log masuk untuk menyimpan kemajuan anda merentas peranti. Sehingga itu, ia disimpan dalam pelayar ini.

Mengapa ini penting

API ialah satu janji. Sebaik sahaja aplikasi mudah alih, rakan kongsi atau ejen bergantung padanya, setiap perubahan boleh merosakkan seseorang yang anda tidak nampak. Pembeli enterprise menilai anda berdasarkan kualiti kontrak API anda.

Hasil pembelajaran

  1. Reka bentuk REST API yang konsisten dengan kontrak OpenAPI.
  2. Jadikan setiap endpoint yang mengubah data idempoten.
  3. Versikan API dan pustaka tanpa merosakkan klien.
  4. Tahu bila gRPC ialah alat yang tepat.

Pelajaran

4.1 Reka bentuk contract-first

  • Tulis spec OpenAPI dahulu; jana jenis, klien, dokumentasi dan mock server daripadanya.
  • Konvensyen yang konsisten: kata nama untuk sumber, laluan jamak, kod status standard, cursor pagination, cap masa ISO 8601.
  • Satu format ralat di mana-mana (RFC 9457 Problem Details): type, title, status, detail, beserta request ID.
  • Validasi setiap input terhadap skema di sempadan; tolak medan yang tidak dikenali.
  • Jangan sekali-kali memulangkan lebih banyak medan daripada yang diperlukan (pendedahan data berlebihan ialah kerentanan API klasik).

4.2 Idempotency (14)

Rangkaian boleh gagal selepas pelayan sudah menyiapkan kerja tetapi sebelum klien menerima jawapan. Klien pun cuba semula. Tanpa idempotency, pelanggan dicaj dua kali.

Corak (seperti yang dipopularkan oleh Stripe):

  1. Klien menghantar Idempotency-Key: <uuid> pada POST.
  2. Pelayan menyimpan kunci + hash permintaan + respons dalam jadual dengan unique constraint.
  3. Kunci yang sama sekali lagi: pulangkan respons yang disimpan, jangan laksanakan semula.
  4. Kunci sama, body berbeza: tolak dengan 422.
  5. Tamatkan tempoh kunci selepas 24 jam atau lebih.

GET, PUT dan DELETE sepatutnya idempoten secara semula jadi. Reka bentuknya begitu.

4.3 Versioning (102, 103)

  • API versioning: URL (/v1/) atau header. Perubahan tambahan (medan pilihan baharu) tidak merosakkan; membuang atau menamakan semula medan, menukar jenis atau semantik adalah perubahan yang merosakkan (breaking).
  • Polisi deprecation: umumkan, tambah header Deprecation dan Sunset, ukur penggunaan versi lama, kemudian buang.
  • Semantic versioning untuk pakej: MAJOR.MINOR.PATCH. MAJOR merosakkan, MINOR menambah, PATCH membaiki. Pin kebergantungan dengan lockfile; jangan percaya bahawa orang lain mematuhi semver dengan sempurna.

4.4 gRPC (100)

Bertaip, binari, pantas, menyokong streaming, di atas HTTP/2. Sangat bagus untuk trafik dalaman servis-ke-servis pada skala besar. Kurang sesuai untuk pelayar dan API awam. Pengasas solo jarang memerlukannya; fahami konsepnya.

4.5 Pratonton keselamatan API

Authorization pada setiap objek (BOLA ialah risiko API nombor satu), rate limit bagi setiap kunci, had pagination, had saiz permintaan. Diperincikan dalam 05 · Keselamatan Aplikasi: OWASP Top 10:2025.

Lab 4: Ship satu kontrak

  1. Tulis spec OpenAPI untuk sumber teras anda; jana klien bertaip.
  2. Tambah idempotency key pada endpoint pembayaran atau "cipta pesanan" anda; tulis ujian yang menghantar permintaan yang sama 5 kali serentak dan assert hanya satu rekod.
  3. Buat perubahan breaking dengan cara yang betul: lepaskan v2 bersama v1 dengan header deprecation.
  4. Ujian kontrak dalam CI gagal jika implementasi menyimpang daripada spec.

Definition of Done

Pek prompt AI

  • "Jana spec OpenAPI 3.1 daripada route ini, kemudian senaraikan ketidakkonsistenan dalam penamaan, kod status dan bentuk ralat."
  • "Tambah idempotency key gaya Stripe pada endpoint ini, disokong oleh jadual Postgres dengan unique constraint. Kendalikan kes duplikat serentak."