Menerapkan versi API berbasis jalur dengan menggunakan domain khusus di Amazon API Gateway - AWS Prescriptive Guidance
RingkasanPrasyarat dan batasanArsitekturAlatPraktik terbaikEpikPemecahan MasalahSumber daya terkaitInformasi tambahan

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menerapkan versi API berbasis jalur dengan menggunakan domain khusus di Amazon API Gateway

Corey Schnedl, Marcelo Barbosa, Mario Lopez Martinez, Anbazhagan Ponnuswamy, Gaurav Samudra, dan Abhilash Vinod, Amazon Web Services

Ringkasan

Pola ini menunjukkan bagaimana Anda dapat menggunakan fitur pemetaan API domain kustom untuk mengimplementasikan solusi versi API berbasis jalur untuk Amazon API Gateway.

Amazon API Gateway adalah layanan terkelola penuh yang dapat Anda gunakan untuk membuat, menerbitkan, memelihara, memantau, dan mengamankan APIs pada skala apa pun. Dengan menggunakan fitur domain kustom layanan, Anda dapat membuat nama domain kustom yang lebih sederhana dengan lebih intuitif URLs yang dapat Anda berikan kepada pengguna API Anda. Anda dapat menggunakan pemetaan API untuk menghubungkan tahapan API ke nama domain kustom. Setelah Anda membuat nama domain dan mengonfigurasi catatan DNS, Anda menggunakan pemetaan API untuk mengirim lalu lintas ke Anda APIs melalui nama domain kustom Anda.

Setelah API tersedia untuk umum, konsumen menggunakannya. Seiring berkembangnya API publik, kontrak layanannya juga berkembang untuk mencerminkan fitur dan kemampuan baru. Namun, tidak bijaksana untuk mengubah atau menghapus fitur yang ada. Setiap perubahan yang melanggar dapat memengaruhi aplikasi konsumen dan merusaknya saat runtime. Pembuatan versi API penting untuk menghindari kerusakan kompatibilitas mundur dan melanggar kontrak.

Anda memerlukan strategi yang jelas untuk pembuatan versi API untuk membantu konsumen mengadopsinya. Pembuatan versi APIs dengan menggunakan berbasis jalur URLs adalah pendekatan yang paling mudah dan umum digunakan. Dalam jenis pembuatan versi ini, versi secara eksplisit didefinisikan sebagai bagian dari API. URIs Contoh berikut URLs menunjukkan bagaimana konsumen dapat menggunakan URI untuk menentukan versi API untuk permintaan mereka:

https://api.example.com/api/v1/orders

https://api.example.com/api/v2/orders

https://api.example.com/api/vX/orders

Pola ini menggunakan AWS Cloud Development Kit (AWS CDK) untuk membangun, menerapkan, dan menguji contoh implementasi solusi versi berbasis jalur yang dapat diskalakan untuk API Anda. AWS CDK adalah kerangka pengembangan perangkat lunak open source untuk memodelkan dan menyediakan sumber daya aplikasi cloud Anda menggunakan bahasa pemrograman yang sudah dikenal.

Prasyarat dan batasan

Prasyarat

  • Aktif Akun AWS.

  • Kepemilikan domain diperlukan untuk menggunakan contoh repositori pola ini dan menggunakan fungsionalitas domain khusus Amazon API Gateway. Anda dapat menggunakan Amazon Route 53 untuk membuat dan mengelola domain untuk organisasi Anda. Untuk informasi tentang cara mendaftar atau mentransfer domain dengan Route 53, lihat Mendaftarkan domain baru di dokumentasi Route 53.

  • Sebelum menyiapkan nama domain khusus untuk API, Anda harus memiliki sertifikat SSL/TLS yang siap. AWS Certificate Manager

  • Anda harus membuat atau memperbarui catatan sumber daya penyedia DNS Anda untuk memetakan ke titik akhir API Anda. Tanpa pemetaan seperti itu, permintaan API yang terikat untuk nama domain khusus tidak dapat mencapai API Gateway.

Keterbatasan

  • Nama domain khusus tidak didukung untuk pribadi APIs.

  • Nama domain khusus harus unik dalam Wilayah AWS semua Akun AWS.

  • Untuk mengonfigurasi pemetaan API dengan beberapa level, Anda harus menggunakan nama domain kustom Regional dan menggunakan kebijakan keamanan TLS 1.2.

  • Dalam pemetaan API, nama domain khusus dan dipetakan APIs harus sama. Akun AWS

  • Pemetaan API harus hanya berisi huruf, angka, dan karakter berikut: $-_.+!*'()/

  • Panjang maksimum jalur dalam pemetaan API adalah 300 karakter.

  • Anda dapat memiliki 200 pemetaan API dengan beberapa level untuk setiap nama domain.

  • Anda hanya dapat memetakan HTTP APIs ke nama domain kustom Regional dengan kebijakan keamanan TLS 1.2.

  • Anda tidak dapat memetakan WebSocket APIs ke nama domain kustom yang sama dengan HTTP API atau REST API.

  • Beberapa Layanan AWS tidak tersedia di semua Wilayah AWS. Untuk ketersediaan Wilayah, lihat AWS Layanan menurut Wilayah. Untuk titik akhir tertentu, lihat Titik akhir dan kuota layanan, dan pilih tautan untuk layanan.

Versi produk

Arsitektur

Diagram berikut menunjukkan alur kerja arsitektur.

Alur kerja menggunakan pemetaan API dan domain khusus untuk mengimplementasikan solusi pembuatan versi API berbasis jalur.

Diagram ini menggambarkan hal sebagai berikut:

  1. Pengguna API mengirimkan permintaan ke Amazon API Gateway dengan nama domain khusus.

  2. API Gateway secara dinamis merutekan permintaan pengguna ke instance dan tahap API Gateway yang sesuai, berdasarkan jalur yang ditunjukkan dalam URL permintaan. Tabel berikut menunjukkan contoh bagaimana jalur berbasis URL yang berbeda dapat dirutekan ke tahapan tertentu untuk berbagai instance API Gateway.

    API

    Stage

    Jalur

    Titik akhir default

    Perhitungan APIv1

    API

    apiv1

    Diaktifkan

    Perhitungan APIv2

    API

    apiv2

    Diaktifkan

    Perhitungan APIv X

    API

    APIVx

    Diaktifkan

  3. Instance API Gateway tujuan memproses permintaan dan mengembalikan hasilnya kepada pengguna.

Otomatisasi dan skala

Kami menyarankan Anda menggunakan AWS CloudFormation tumpukan terpisah untuk setiap versi API Anda. Dengan pendekatan ini, Anda dapat memiliki isolasi lengkap antara backend APIs yang dapat dirutekan oleh fitur pemetaan API domain kustom. Keuntungan dari pendekatan ini adalah bahwa versi berbeda dari API Anda dapat digunakan atau dihapus secara independen tanpa menimbulkan risiko memodifikasi API lain. Pendekatan ini meningkatkan ketahanan melalui isolasi tumpukan. CloudFormation Selain itu, ini memberi Anda opsi back-end yang berbeda untuk API Anda seperti AWS Lambda, AWS Fargate, titik akhir HTTP, dan tindakan. Layanan AWS

Anda dapat menggunakan strategi percabangan Git, seperti Gitflow, dalam kombinasi dengan CloudFormation tumpukan terisolasi untuk mengelola kode sumber yang diterapkan ke versi API yang berbeda. Dengan menggunakan opsi ini, Anda dapat mempertahankan versi API yang berbeda tanpa perlu menduplikasi kode sumber untuk versi baru. Dengan Gitflow, Anda dapat menambahkan tag ke commit dalam repositori git Anda saat rilis dilakukan. Akibatnya, Anda memiliki snapshot lengkap dari kode sumber yang terkait dengan rilis tertentu. Karena pembaruan perlu dilakukan, Anda dapat memeriksa kode dari rilis tertentu, membuat pembaruan, dan kemudian menyebarkan kode sumber yang diperbarui ke CloudFormation tumpukan yang sejajar dengan versi utama yang sesuai. Pendekatan ini mengurangi risiko melanggar versi API lain karena setiap versi API memiliki kode sumber yang terisolasi dan digunakan untuk CloudFormation tumpukan terpisah.

Alat

Layanan AWS

  • Amazon API Gateway membantu Anda membuat, menerbitkan, memelihara, memantau, dan mengamankan REST, HTTP, dan WebSocket APIs dalam skala apa pun.

  • AWS Certificate Manager (ACM) membantu Anda membuat, menyimpan, dan memperbarui sertifikat dan kunci SSL/TLS X.509 publik dan pribadi yang melindungi situs web dan aplikasi Anda. AWS

  • AWS Cloud Development Kit (AWS CDK)adalah kerangka pengembangan perangkat lunak open-source untuk mendefinisikan infrastruktur cloud Anda dalam kode dan menyediakannya. AWS CloudFormation Implementasi sampel pola ini menggunakan AWS CDK in TypeScript. Bekerja dengan AWS CDK in TypeScript menggunakan alat yang sudah dikenal, termasuk Microsoft TypeScript compiler (tsc), Node.js, dan node package manager (npm). Jika mau, Anda dapat menggunakan Yarn meskipun contoh dalam pola ini digunakannpm. Modul yang terdiri dari AWS Construct Library didistribusikan melalui npm repositori, npmjs.org.

  • AWS CloudFormationmembantu Anda menyiapkan AWS sumber daya, menyediakannya dengan cepat dan konsisten, dan mengelolanya sepanjang siklus hidupnya di seluruh Akun AWS dan. Wilayah AWS

  • AWS Lambdaadalah layanan komputasi yang membantu Anda menjalankan kode tanpa perlu menyediakan atau mengelola server. Ini menjalankan kode Anda hanya bila diperlukan dan skala secara otomatis, jadi Anda hanya membayar untuk waktu komputasi yang Anda gunakan.

  • Amazon Route 53 adalah layanan web DNS yang sangat tersedia dan dapat diskalakan.

  • AWS WAFadalah firewall aplikasi web yang membantu Anda memantau permintaan HTTP dan HTTPS yang diteruskan ke sumber daya aplikasi web Anda yang dilindungi.

Alat lainnya

  • Bruno adalah klien pengujian API open source yang ramah git-friendly.

  • cdk-nag adalah utilitas open source yang memeriksa AWS CDK aplikasi untuk praktik terbaik dengan menggunakan paket aturan.

Repositori kode

Kode untuk pola ini tersedia di repositori GitHub path-based-versioning-with-api-gateway.

Praktik terbaik

  • Gunakan pipeline integrasi berkelanjutan dan pengiriman berkelanjutan (CI/CD) yang kuat untuk mengotomatiskan pengujian dan penyebaran CloudFormation tumpukan Anda yang dibangun dengan. AWS CDK Untuk informasi lebih lanjut terkait dengan rekomendasi ini, lihat Panduan AWS DevOps Well-Architected.

  • AWS WAF adalah firewall terkelola yang mudah diintegrasikan dengan layanan seperti Amazon API Gateway. Meskipun AWS WAF bukan merupakan komponen yang diperlukan agar pola pembuatan versi ini berfungsi, kami merekomendasikan sebagai praktik terbaik keamanan untuk disertakan AWS WAF dengan API Gateway.

  • Dorong konsumen API untuk memutakhirkan secara berkala ke versi terbaru API Anda sehingga versi API yang lebih lama dapat dihentikan dan dihapus secara efisien.

  • Sebelum menggunakan pendekatan ini dalam pengaturan produksi, terapkan firewall dan strategi otorisasi untuk API Anda.

  • Terapkan akses ke pengelolaan sumber AWS daya Anda Akun AWS dengan menggunakan model akses hak istimewa paling sedikit.

  • Untuk menerapkan praktik terbaik dan rekomendasi keamanan untuk aplikasi yang dibangun dengan AWS CDK, kami sarankan Anda menggunakan utilitas cdk-nag.

Epik

TugasDeskripsiKeterampilan yang dibutuhkan

Kloning repositori.

Untuk mengkloning repositori aplikasi sampel, jalankan perintah berikut:

git clone https://github.com/aws-samples/path-based-versioning-with-api-gateway
Pengembang aplikasi

Arahkan ke repositori kloning.

Untuk menavigasi ke lokasi folder repositori kloning, jalankan perintah berikut: 

cd api-gateway-custom-domain-versioning
Pengembang aplikasi

Instal dependensi yang diperlukan.

Untuk menginstal dependensi yang diperlukan, jalankan perintah berikut:

npm install
Pengembang aplikasi
TugasDeskripsiKeterampilan yang dibutuhkan

Memulai penyebaran tumpukan routing.

Untuk memulai penyebaran tumpukan CloudFormation routingCustomDomainRouterStack, jalankan perintah berikut, ganti example.com dengan nama domain yang Anda miliki:

npx cdk deploy CustomDomainRouterStack --parameters PrerequisiteDomainName=example.com
catatan

Penyebaran tumpukan tidak akan berhasil sampai tugas validasi DNS domain berikut berhasil dilakukan.

Pengembang aplikasi
TugasDeskripsiKeterampilan yang dibutuhkan

Verifikasi kepemilikan domain Anda.

Sertifikat akan tetap dalam status validasi Tertunda sampai Anda membuktikan kepemilikan domain terkait.

Untuk membuktikan kepemilikan, tambahkan catatan CNAME ke zona yang dihosting yang terkait dengan domain. Untuk informasi selengkapnya, lihat validasi DNS dalam dokumentasi. AWS Certificate Manager

Menambahkan catatan yang sesuai memungkinkan CustomDomainRouterStack penerapan berhasil.

Pengembang aplikasi, administrator sistem AWS, Administrator jaringan

Buat catatan alias untuk menunjuk ke domain kustom API Gateway Anda.

Setelah sertifikat diterbitkan dan divalidasi dengan sukses, buat catatan DNS yang mengarah ke URL domain kustom Amazon API Gateway Anda.

URL domain kustom dihasilkan secara unik oleh penyediaan domain kustom dan ditentukan sebagai parameter output. CloudFormation Berikut ini adalah contoh catatan:

Kebijakan perutean: Perutean sederhana

Nama rekam: demo.api-gateway-custom-domain-versioning.example.com

Alias: Ya

Jenis rekaman: Catatan DNS tipe “A” yang menunjuk ke sumber daya AWS

Nilai: d-xxxxxxxxxx.execute-api.xx-xxxx-x.amazonaws.com

TTL (detik): 300

Pengembang aplikasi, administrator sistem AWS, Administrator jaringan
TugasDeskripsiKeterampilan yang dibutuhkan

Menyebarkan ApiStackV1 tumpukan.

Untuk menyebarkan ApiStackV1 tumpukan, gunakan perintah berikut:

npm run deploy-v1

Kode CDK berikut menambahkan pemetaan API:

var apiMapping = new CfnApiMapping(this, "ApiMapping", {
      apiId: this.lambdaRestApi.restApiId,
      domainName: props.customDomainName.domainName,
      stage: "api",
      apiMappingKey: "api/v1",
    });
Pengembang aplikasi

Menyebarkan ApiStackV2 tumpukan.

Untuk menyebarkan ApiStackV2 tumpukan, gunakan perintah berikut:

npm run deploy-v2
Pengembang aplikasi

Memanggil API.

Untuk menjalankan API dan menguji titik akhir API menggunakan Bruno, lihat petunjuk di Informasi tambahan.

Pengembang aplikasi
TugasDeskripsiKeterampilan yang dibutuhkan

Pembersihan sumber daya

Untuk menghancurkan sumber daya yang terkait dengan aplikasi sampel ini, gunakan perintah berikut:

npx cdk destroy --all
catatan

Pastikan Anda membersihkan semua catatan DNS Route 53 yang ditambahkan secara manual untuk proses verifikasi kepemilikan domain.

Pengembang aplikasi

Pemecahan Masalah

IsuSolusi

Penerapan CustomDomainRouterStack waktu habis karena sertifikat tidak dapat divalidasi.

Pastikan Anda menambahkan catatan CNAME validasi DNS yang tepat seperti yang dijelaskan dalam tugas sebelumnya. Sertifikat baru Anda mungkin terus menampilkan status validasi Tertunda hingga 30 menit setelah menambahkan catatan validasi DNS. Untuk informasi selengkapnya, lihat validasi DNS dalam dokumentasi. AWS Certificate Manager

Sumber daya terkait

  • Menerapkan versi API Gateway berbasis header dengan CloudFront Amazon - Posting Blog Komputasi AWS ini menawarkan strategi pembuatan versi berbasis header sebagai alternatif strategi pembuatan versi berbasis jalur yang diuraikan dalam pola ini.

  • AWS CDK Workshop — Lokakarya pengantar ini berfokus pada membangun dan menerapkan aplikasi AWS dengan menggunakan. AWS Cloud Development Kit (AWS CDK) Workshop ini mendukung Go, Python, dan. TypeScript

Informasi tambahan

Menguji API Anda dengan Bruno

Kami menyarankan Anda menggunakan Bruno, alat pengujian API open source, untuk memverifikasi bahwa routing berbasis jalur berfungsi dengan baik untuk aplikasi sampel. Pola ini menyediakan koleksi sampel untuk memfasilitasi pengujian API sampel Anda.

Untuk memanggil dan menguji API Anda, gunakan langkah-langkah berikut:

  1. Instal Bruno.

  2. Buka Bruno.

  3. Dalam repositori kode pola ini, pilih Bruno/Sample-API - dan buka koleksi. Gateway-Custom-Domain-Versioning

  4. Untuk melihat dropdown Environments di kanan atas antarmuka pengguna (UI), pilih permintaan apa pun dalam koleksi.

  5. Di dropdown Environments, pilih Configure.

  6. Ganti REPLACE_ME_WITH_YOUR_DOMAIN nilainya dengan domain kustom Anda.

  7. Pilih Simpan, lalu tutup bagian Konfigurasi.

  8. Untuk Sandbox Environment, verifikasi bahwa opsi Aktif dipilih.

  9. Panggil API Anda dengan menggunakan tombol -> untuk permintaan yang dipilih.

  10. Perhatikan bagaimana validasi (meneruskan nilai non-angka) ditangani di V1 dibandingkan dengan V2.

Untuk melihat tangkapan layar contoh pemanggilan API dan perbandingan validasi V1 dan V2, lihat Menguji API sampel Anda dalam README.md file di repositori kode pola ini.