REL03-BP03 Memberikan kontrak layanan per API

Kontrak layanan adalah perjanjian-perjanjian yang didokumentasikan yang dibuat antara produsen dan konsumen API yang ditetapkan dalam definisi API yang dapat dibaca mesin. Strategi penentuan versi kontrak memungkinkan konsumen untuk terus menggunakan API yang ada dan memigrasikan aplikasi mereka ke API yang lebih baru ketika mereka siap. Deployment oleh produsen dapat terjadi kapan saja, selama kontrak dipatuhi. Tim layanan dapat menggunakan tumpukan teknologi pilihan mereka untuk memenuhi kontrak API tersebut.

Hasil yang diinginkan:

Anti-pola 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 akan mengganggu stabilitas sistem secara keseluruhan ketika kedua belah pihak mematuhi kontrak API yang sama. Komponen-komponen yang berkomunikasi melalui API layanan dapat melakukan rilis fungsional independen, peningkatan ke dependensi runtime, atau melakukan failover ke situs pemulihan bencana (DR) dengan hanya menimbulkan sedikit dampak, atau bahkan tanpa dampak sama sekali, terhadap satu sama lain. Selain itu, layanan-layanan diskret dapat menyesuaikan skala secara independen dengan menyerap permintaan sumber daya tanpa mengharuskan layanan lain untuk menyesuaikan skala (menskalakan) secara serempak.

• Membuat API layanan tanpa menggunakan skema strongly-typed. Hal ini akan menghasilkan API yang tidak dapat digunakan untuk membuat pengikatan dan juga menghasilkan muatan API yang tidak dapat divalidasi secara terprogram.

• Tidak mengadopsi strategi penentuan versi, yang memaksa konsumen API untuk memperbarui dan melepaskan atau gagal saat kontrak layanan berkembang.

• Pesan-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 agar pengujian komponen layanan secara independen bisa dilakukan.

Manfaat menerapkan praktik terbaik ini: Sistem terdistribusi yang terdiri dari komponen-komponen yang melakukan komunikasi melalui kontrak layanan API dapat meningkatkan keandalan. Pengembang dapat mengidentifikasi potensi masalah di awal proses pengembangan dengan melakukan pemeriksaan tipe selama kompilasi untuk memastikan bahwa bidang-bidang yang diperlukan sudah ada dan bahwa permintaan serta respons sudah mematuhi kontrak API. Kontrak API menyediakan sebuah 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 diterapkan: Sedang

Panduan implementasi

Setelah mengidentifikasi domain bisnis dan menentukan segmentasi beban kerja, Anda dapat mengembangkan API layanan Anda. Pertama-tama, tentukan kontrak layanan yang dapat dibaca mesin untuk API, lalu implementasikan strategi penentuan versi API. Setelah Anda siap mengintegrasikan layanan melalui protokol umum seperti REST, GraphQL, atau peristiwa asinkron, Anda dapat memasukkan layanan-layanan AWS ke dalam arsitektur Anda untuk mengintegrasikan komponen-komponen Anda dengan kontrak API strongly-typed.

Layanan-layanan AWS untuk kontrak API layanan

Menggabungkan layanan-layanan AWS termasuk Amazon API Gateway, AWS AppSync, dan Amazon EventBridge ke dalam arsitektur Anda untuk menggunakan kontrak layanan API dalam aplikasi Anda. Amazon API Gateway membantu Anda berintegrasi dengan layanan AWS native secara langsung dan layanan-layanan web lainnya. API Gateway mendukung spesifikasi dan penentuan versi OpenAPI. AWS AppSync adalah sebuah titik akhir GraphQL terkelola yang Anda konfigurasikan dengan mendefinisikan skema GraphQL untuk menentukan antarmuka layanan untuk kueri, mutasi, dan berlangganan. Amazon EventBridge menggunakan skema peristiwa untuk menentukan peristiwa dan menghasilkan binding kode untuk peristiwa Anda.

Langkah-langkah implementasi

• Pertama-tama, tetapkan kontrak untuk API Anda. Sebuah 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 akan 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 akan menyederhanakan integrasi dengan alat pengujian API dan menyediakan spesifikasi integrasi untuk konsumen layanan.

• Anda dapat menentukan dan mengelola GraphQL API dengan menggunakan AWS AppSync dengan mendefinisikan file skema GraphQL untuk menghasilkan antarmuka kontrak Anda dan menyederhanakan interaksi dengan model REST yang kompleks, beberapa tabel basis data, atau layanan warisan.

• Proyek-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 sebuah skema yang ditentukan dalam registri tersebut, Anda juga dapat menghasilkan pengikatan klien (client binding) dari kontrak skema tersebut untuk mengintegrasikan kode Anda dengan peristiwa.

• Memperluas atau melakukan penentuan versi API Anda. Memperluas sebuah API adalah opsi yang lebih sederhana saat menambahkan bidang-bidang yang dapat dikonfigurasi dengan bidang-bidang opsional atau nilai default untuk bidang-bidang wajib.

  • Kontrak berbasis JSON untuk protokol seperti REST dan GraphQL bisa menjadi kontrak yang ideal untuk perluasan kontrak.

  • Kontrak berbasis XML untuk protokol seperti SOAP harus diuji dengan para konsumen layanan untuk menentukan kelayakan perluasan kontrak.

• Saat melakukan penentuan versi API, pertimbangkan implementasi penentuan versi 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-layanan yang mendasari dapat mempertahankan satu basis kode tunggal.

Sumber daya

Praktik-praktik terbaik terkait:

• REL03-BP01 Memilih cara untuk menyegmentasi beban kerja

• REL03-BP02 Bangun layanan yang berfokus pada domain dan fungsionalitas bisnis khusus

• REL04-BP02 Mengimplementasikan dependensi yang digabungkan secara longgar

• REL05-BP03 Mengontrol dan membatasi panggilan percobaan ulang

• REL05-BP05 Mengatur batas waktu klien

Dokumen terkait:

• Apa itu API (Antarmuka Pemrograman Aplikasi)?

• Mengimplementasikan Layanan Mikro di AWS

• Kompensasi Layanan Mikro

• Layanan mikro - definisi dari istilah arsitektur baru ini

• Layanan mikro di AWS

• Bekerja dengan ekstensi API Gateway ke OpenAPI

• OpenAPI-Specification

• GraphQL: Skema dan Jenis

• Pengikatan kode Amazon EventBridge

Contoh terkait:

• Amazon API Gateway: Mengonfigurasi API REST Menggunakan OpenAPI

• Amazon API Gateway ke aplikasi Amazon DynamoDB CRUD menggunakan OpenAPI

• Pola integrasi aplikasi modern di era nirserver: Integrasi Layanan API Gateway

• Menerapkan penentuan versi API Gateway berbasis header dengan Amazon CloudFront

• AWS AppSync: Membangun aplikasi klien

Video terkait:

• Menggunakan OpenAPI di AWS SAM untuk mengelola API Gateway

Alat terkait:

• Amazon API Gateway

• AWS AppSync

• Amazon EventBridge