REL03-BP03 Memberikan kontrak layanan per API
Kontrak layanan adalah perjanjian terdokumentasi antara produsen dan konsumen API yang ditetapkan dalam definisi API yang dapat dibaca mesin. Strategi versioning kontrak memungkinkan konsumen untuk terus menggunakan API yang ada dan memigrasikan aplikasi mereka ke API yang lebih baru ketika mereka siap. Deployment produsen dapat terjadi kapan saja, selama kontrak dipatuhi. Tim layanan dapat menggunakan tumpukan teknologi pilihan mereka untuk memenuhi kontrak API.
Hasil yang diinginkan:
Antipola umum: Aplikasi yang dibangun dengan arsitektur berorientasi layanan atau layanan mikro dapat beroperasi secara independen sementara tetap memiliki dependensi runtime yang terintegrasi. Perubahan yang di-deploy ke konsumen atau produsen API tidak mengganggu stabilitas sistem secara keseluruhan ketika kedua belah pihak mematuhi kontrak API yang sama. Komponen yang berkomunikasi melalui API layanan dapat melakukan rilis fungsional independen, peningkatan ke dependensi runtime, atau melakukan failover ke situs pemulihan bencana (DR) dengan sedikit atau tanpa dampak terhadap satu sama lain. Selain itu, layanan diskret dapat menyesuaikan skala secara independen dengan menyerap permintaan sumber daya tanpa mengharuskan layanan lain untuk menyesuaikan skala secara serempak.
-
Membuat API layanan tanpa skema strongly-typed. Hal ini menghasilkan API yang tidak dapat digunakan untuk menghasilkan pengikatan dan muatan API yang tidak dapat divalidasi secara terprogram.
-
Tidak mengadopsi strategi versioning, yang memaksa konsumen API untuk memperbarui dan melepaskan atau gagal saat kontrak layanan berkembang.
-
Pesan kesalahan yang membocorkan detail implementasi layanan yang mendasari, bukan menggambarkan kegagalan integrasi dalam bahasa dan konteks domain.
-
Tidak menggunakan kontrak API untuk mengembangkan kasus pengujian dan implementasi API simulasi untuk memungkinkan pengujian komponen layanan secara independen.
Manfaat menjalankan praktik terbaik ini: Sistem terdistribusi yang terdiri dari komponen-komponen yang berkomunikasi melalui kontrak layanan API dapat meningkatkan keandalan. Developer dapat mengidentifikasi potensi masalah di awal proses pengembangan dengan pemeriksaan tipe selama kompilasi untuk memverifikasi bahwa bidang-bidang yang diperlukan ada dan permintaan serta respons mematuhi kontrak API. Kontrak API menyediakan antarmuka dokumentasi mandiri yang jelas untuk API dan menyediakan interoperabilitas yang lebih baik antara sistem dan bahasa pemrograman yang berbeda.
Tingkat risiko yang terjadi jika praktik terbaik ini tidak dijalankan: Sedang
Panduan implementasi
Setelah mengidentifikasi domain bisnis dan menentukan segmentasi beban kerja, Anda dapat mengembangkan API layanan. Pertama-tama, tentukan kontrak layanan yang dapat dibaca mesin untuk API, lalu implementasikan strategi versioning API. Setelah siap mengintegrasikan layanan melalui protokol umum seperti REST, GraphQL, atau peristiwa asinkron, Anda dapat memasukkan layanan AWS ke dalam arsitektur Anda untuk mengintegrasikan komponen Anda dengan kontrak API strongly-typed.
Layanan AWS untuk kontrak API layanan
Sertakan layanan AWS seperti Amazon API Gateway
Langkah implementasi
-
Pertama-tama, tetapkan kontrak untuk API Anda. Kontrak akan mengekspresikan kemampuan suatu API serta menetapkan objek dan bidang data strongly-typed untuk input dan output API.
-
Saat mengonfigurasi API di API Gateway, Anda dapat mengimpor dan mengekspor OpenAPI Specification untuk titik akhir Anda.
-
Mengimpor definisi OpenAPI menyederhanakan pembuatan API Anda dan dapat diintegrasikan dengan infrastruktur AWS sebagai alat kode seperti AWS Serverless Application Model
dan AWS Cloud Development Kit (AWS CDK) . -
Mengekspor definisi API menyederhanakan integrasi dengan alat pengujian API dan menyediakan spesifikasi integrasi untuk konsumen layanan.
-
-
Anda dapat menetapkan dan mengelola API GraphQL dengan AWS AppSync dengan cara menetapkan file skema GraphQL untuk menghasilkan antarmuka kontrak Anda dan menyederhanakan interaksi dengan model REST kompleks, beberapa tabel basis data, atau layanan warisan.
-
Proyek AWS Amplify
yang terintegrasi dengan AWS AppSync menghasilkan file kueri JavaScript strongly-typed untuk digunakan dalam aplikasi Anda serta pustaka klien GraphQL AWS AppSync untuk tabel Amazon DynamoDB . -
Saat Anda menggunakan peristiwa layanan dari Amazon EventBridge, peristiwa mematuhi skema yang sudah ada di dalam registri skema atau yang Anda definisikan dengan OpenAPI Spec. Dengan skema yang didefinisikan dalam registri, Anda juga dapat menghasilkan binding klien dari kontrak skema untuk mengintegrasikan kode Anda dengan peristiwa.
-
Memperluas atau melakukan versioning API Anda. Memperluas API adalah opsi yang lebih sederhana saat menambahkan bidang yang dapat dikonfigurasi dengan bidang opsional atau nilai default untuk bidang wajib.
-
Kontrak berbasis JSON untuk protokol seperti REST dan GraphQL bisa ideal untuk perluasan kontrak.
-
Kontrak berbasis XML untuk protokol seperti SOAP harus diuji dengan konsumen layanan untuk menentukan kelayakan perluasan kontrak.
-
-
Saat melakukan versioning API, pertimbangkan implementasi versioning proksi yang menggunakan facade untuk mendukung versi sehingga logika dapat dipertahankan dalam satu basis kode.
-
Dengan API Gateway Anda dapat menggunakan pemetaan permintaan dan respons untuk menyederhanakan penyerapan perubahan kontrak dengan membuat facade untuk memberikan nilai default untuk bidang baru atau untuk membuang bidang yang dihapus dari permintaan atau respons. Dengan pendekatan ini, layanan yang mendasari dapat mempertahankan basis kode tunggal.
-
Sumber daya
Praktik terbaik terkait:
Dokumen terkait:
Contoh terkait:
Video terkait:
Alat terkait:
