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 kustom 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html) [domain kustom](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html) 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 membuat nama domain dan mengonfigurasi catatan DNS, Anda menggunakan pemetaan API untuk mengirim lalu lintas ke nama domain khusus Anda. APIs 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](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register-update.html) di dokumentasi Route 53. + Sebelum menyiapkan nama domain khusus untuk API, Anda harus memiliki sertifikat [SSL/TLS](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-specify-certificate-for-custom-domain-name.html) yang siap. AWS Certificate Manager + Anda harus membuat atau memperbarui catatan sumber daya penyedia DNS Anda untuk dipetakan ke titik akhir API Anda. Tanpa pemetaan seperti itu, permintaan API yang terikat untuk nama domain khusus tidak dapat mencapai API Gateway. **Keterbatasan** + Sebuah nama domain kustom 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](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). Untuk titik akhir tertentu, lihat [Titik akhir dan kuota layanan](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html), dan pilih tautan untuk layanan. **Versi produk** + Implementasi sampel ini digunakan [AWS CDK dalam TypeScript](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-typescript.html) versi 2.149.0. ## Arsitektur Diagram berikut menunjukkan alur kerja arsitektur. ![\[Alur kerja menggunakan pemetaan API dan domain khusus untuk mengimplementasikan solusi pembuatan versi API berbasis jalur.\]](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/images/pattern-img/e1b32d2b-410f-4ace-967e-f0b8aaf0304c/images/fa9f04f1-efa6-4fb1-a541-ae3da4076b00.png) Diagram ini menggambarkan hal sebagai berikut: 1. Pengguna API mengirimkan permintaan ke Amazon API Gateway dengan nama domain khusus. 1. 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/implement-path-based-api-versioning-by-using-custom-domains.html) 1. 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](https://docs.aws.amazon.com/prescriptive-guidance/latest/choosing-git-branch-approach/gitflow-branching-strategy.html), 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 komit 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) membantu Anda membuat, menerbitkan, memelihara, memantau, dan mengamankan REST, HTTP, dan WebSocket APIs dalam skala apa pun. + [AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html) 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)](https://docs.aws.amazon.com/cdk/v2/guide/home.html)adalah kerangka pengembangan perangkat lunak open-source untuk mendefinisikan infrastruktur cloud Anda dalam kode dan menyediakannya. CloudFormation Implementasi sampel pola ini menggunakan [AWS CDK in TypeScript](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-typescript.html). Bekerja dengan AWS CDK in TypeScript menggunakan alat yang sudah dikenal, termasuk Microsoft TypeScript compiler (`tsc`), [Node.js](https://nodejs.org/), dan node package manager (`npm`). Jika mau, Anda dapat menggunakan [Yarn](https://yarnpkg.com/) meskipun contoh dalam pola ini digunakan`npm`. [Modul yang terdiri dari [AWS Construct Library](https://docs.aws.amazon.com/cdk/v2/guide/libraries.html#libraries-construct) didistribusikan melalui `npm ` repositori, npmjs.org.](https://docs.npmjs.com/) + [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)membantu Anda menyiapkan AWS sumber daya, menyediakannya dengan cepat dan konsisten, dan mengelolanya sepanjang siklus hidupnya di seluruh Akun AWS dan. Wilayah AWS + [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)adalah 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](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html) adalah layanan web DNS yang sangat tersedia dan dapat diskalakan. + [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/what-is-aws-waf.html)adalah firewall aplikasi web yang membantu Anda memantau permintaan HTTP dan HTTPS yang diteruskan ke sumber daya aplikasi web Anda yang dilindungi. **Alat-alat lainnya** + [Bruno](https://www.usebruno.com/) adalah klien pengujian API open source yang ramah git-friendly. + [cdk-nag](https://github.com/cdklabs/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](https://github.com/aws-samples/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](https://docs.aws.amazon.com/wellarchitected/latest/devops-guidance/devops-guidance.html). + 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). + Untuk menerapkan praktik terbaik dan rekomendasi keamanan untuk aplikasi yang dibangun dengan AWS CDK, kami sarankan Anda menggunakan utilitas [cdk-nag](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/check-aws-cdk-applications-or-cloudformation-templates-for-best-practices-by-using-cdk-nag-rule-packs.html). ## Epik ### Persiapkan lingkungan lokal Anda | Tugas | Deskripsi | Keterampilan 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 | ### Terapkan tumpukan CloudFormation perutean | Tugas | Deskripsi | Keterampilan yang dibutuhkan | | --- | --- | --- | | Memulai penyebaran tumpukan routing. | Untuk memulai penyebaran tumpukan CloudFormation routing`CustomDomainRouterStack`, jalankan perintah berikut, ganti `example.com` dengan nama domain yang Anda miliki:
npx cdk deploy CustomDomainRouterStack --parameters PrerequisiteDomainName=example.com
Penyebaran tumpukan tidak akan berhasil sampai tugas validasi DNS domain berikut berhasil dilakukan. | Pengembang aplikasi | ### Memverifikasi kepemilikan domain | Tugas | Deskripsi | Keterampilan 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](https://docs.aws.amazon.com/acm/latest/userguide/dns-validation.html) 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-regional-api-custom-domain-create.html#apigateway-regional-api-custom-domain-dns-record) 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](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-basic.html): **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 | ### Menerapkan CloudFormation tumpukan dan menjalankan API | Tugas | Deskripsi | Keterampilan 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.](#implement-path-based-api-versioning-by-using-custom-domains-additional) | Pengembang aplikasi | ### Pembersihan sumber daya | Tugas | Deskripsi | Keterampilan yang dibutuhkan | | --- | --- | --- | | Pembersihan sumber daya | Untuk menghancurkan sumber daya yang terkait dengan aplikasi sampel ini, gunakan perintah berikut:
npx cdk destroy --all
Pastikan Anda membersihkan semua catatan DNS Route 53 yang ditambahkan secara manual untuk proses verifikasi kepemilikan domain. | Pengembang aplikasi | ## Pemecahan masalah | Isu | Solusi | | --- | --- | | 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](https://docs.aws.amazon.com/acm/latest/userguide/dns-validation.html) dalam dokumentasi. AWS Certificate Manager | ## Sumber daya terkait + [Menerapkan versi API Gateway berbasis header dengan CloudFront Amazon](https://aws.amazon.com/blogs/compute/implementing-header-based-api-gateway-versioning-with-amazon-cloudfront/) - 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](https://cdkworkshop.com/20-typescript.html) — 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](https://www.usebruno.com/), 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.](https://www.usebruno.com/downloads) 1. Buka Bruno. 1. Dalam [repositori kode](https://github.com/aws-samples/path-based-versioning-with-api-gateway) pola ini, pilih **Bruno/Sample-API** - dan buka koleksi. Gateway-Custom-Domain-Versioning 1. Untuk melihat dropdown **Environments** di kanan atas antarmuka pengguna (UI), pilih permintaan apa pun dalam koleksi. 1. **Di dropdown **Environments**, pilih Configure.** 1. Ganti `REPLACE_ME_WITH_YOUR_DOMAIN` nilainya dengan domain kustom Anda. 1. Pilih **Simpan**, lalu tutup bagian **Konfigurasi**. 1. Untuk **Sandbox Environment**,**** verifikasi bahwa opsi **Aktif** dipilih. 1. Panggil API Anda dengan menggunakan tombol **->** untuk permintaan yang dipilih. 1. 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.](https://github.com/aws-samples/path-based-versioning-with-api-gateway)