Menggunakan DevOps dan CI/CD untuk menerbitkan API

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Dengan nilai strategis API di perusahaan, mengadopsi teknik integrasi berkelanjutan (CI) dan penyebaran (CD) DevOps telah menjadi aspek penting dalam pengembangan API. Artikel ini membahas keputusan yang perlu Anda buat guna mengadopsi prinsip DevOps untuk manajemen API.

API DevOps terdiri dari tiga bagian:

Diagram yang menggambarkan alur API DevOps.

Setiap bagian dari alur API DevOps dibahas di bawah ini.

Definisi API

Pengembang API menulis definisi API dengan memberikan spesifikasi, pengaturan (seperti pengelogan, diagnostik, dan pengaturan backend), serta kebijakan yang akan diterapkan ke API. Definisi API menyediakan informasi yang diperlukan untuk menyediakan API pada layanan Azure API Management. Spesifikasi dapat didasarkan pada spesifikasi API berbasis standar (seperti WSDL, OpenAPI, atau GraphQL), atau dapat ditentukan menggunakan API Azure Resource Manager (ARM) (misalnya, templat ARM yang menjelaskan API dan operasi). Definisi API akan berubah dari waktu ke waktu dan harus dianggap sebagai "kode sumber". Pastikan bahwa definisi API disimpan di bawah kontrol kode sumber dan memiliki tinjauan yang sesuai sebelum adopsi.

Ada beberapa alat untuk membantu memproduksi definisi API:

  • Azure APIOps Toolkit menyediakan alur kerja yang dibangun di atas sistem kontrol kode sumber git (seperti GitHub atau Azure Repos). Ini menggunakan ekstraktor untuk menghasilkan definisi API yang kemudian diterapkan ke layanan API Management target oleh penerbit. APIOps mendukung REST dan GraphQL API saat ini.
  • Alat dotnet-apim mengonversi definisi YAML yang terbentuk dengan baik menjadi templat ARM untuk penyebaran nanti. Alat ini difokuskan pada REST API.
  • Terraform adalah alternatif untuk Azure Resource Manager untuk mengonfigurasi sumber daya di Azure. Anda dapat membuat konfigurasi Terraform (beserta kebijakan) untuk mengimplementasikan API dengan cara yang sama seperti templat ARM dibuat.

Anda juga dapat menggunakan alat berbasis IDE untuk editor seperti Visual Studio Code guna menghasilkan artefak yang diperlukan untuk menentukan API. Misalnya, ada lebih dari 30 plugin untuk mengedit file spesifikasi OpenAPI di Marketplace Visual Studio Code. Anda juga dapat menggunakan generator kode untuk membuat artefak. Bahasa CADL memungkinkan Anda dengan mudah membuat blok penyusun tingkat tinggi dan kemudian membuat kompilasi ke dalam format definisi API standar seperti OpenAPI.

Persetujuan API

Setelah definisi API diproduksi, pengembang akan mengirimkan definisi API untuk ditinjau dan disetujui. Jika menggunakan sistem kontrol kode sumber berbasis git (seperti GitHub atau Azure Repos), pengiriman dapat dilakukan melalui Permintaan Pull. Permintaan pull memberi tahu orang lain tentang perubahan yang telah diusulkan ke definisi API. Setelah gerbang persetujuan dikonfirmasi, pemberi persetujuan akan menggabungkan permintaan pull ke repositori utama untuk menandakan bahwa definisi API dapat disebarkan ke produksi. Proses permintaan pull memberdayakan pengembang untuk memulihkan masalah apa pun yang ditemukan selama proses persetujuan.

GitHub dan Azure Repos memungkinkan alur persetujuan dikonfigurasi saat permintaan pull diajukan. Anda dapat mengonfigurasi alur persetujuan untuk menjalankan alat seperti:

  • Linter spesifikasi API seperti Spectral untuk memastikan bahwa definisi memenuhi standar API yang diperlukan oleh organisasi.
  • Deteksi perubahan utama menggunakan alat seperti openapi-diff.
  • Audit keamanan dan alat penilaian. OWASP mempertahankan daftar alat untuk pemindaian keamanan.
  • Kerangka kerja pengujian API otomatis seperti Newman, runner pengujian untuk koleksi Postman.

Catatan

API Azure harus sesuai dengan serangkaian pedoman yang ketat yang dapat Anda gunakan sebagai titik awal untuk pedoman API Anda sendiri. Ada konfigurasi Spectral untuk menegakkan pedoman.

Setelah alat otomatis dijalankan, definisi API ditinjau oleh mata manusia. Alat tidak akan menangkap semua masalah. Peninjau manusia memastikan bahwa definisi API memenuhi kriteria organisasi untuk API, termasuk kepatuhan terhadap pedoman keamanan, privasi, dan konsistensi.

Publikasi API

Definisi API akan diterbitkan ke layanan API Management melalui alur rilis. Alat yang digunakan untuk menerbitkan definisi API bergantung pada alat yang digunakan untuk menghasilkan definisi API:

Dapatkah saya menggunakan kontrol kode sumber dan sistem CI/CD lain?

Ya. Proses yang dijelaskan berfungsi dengan sistem kontrol kode sumber apa pun (meskipun APIOps memang mengharuskan sistem kontrol kode sumber berbasis git). Demikian pula, Anda dapat menggunakan platform CI/CD apa pun selama dapat dipicu dalam pemeriksaan dan menjalankan alat baris perintah yang berkomunikasi dengan Azure.

Praktik terbaik

Tidak ada standar industri dalam menyiapkan alur DevOps untuk menerbitkan API, dan tidak ada alat yang disebutkan yang akan berfungsi dalam semua situasi. Namun, kami melihat bahwa sebagian besar situasi tercakup dengan menggunakan kombinasi alat dan layanan berikut:

Kami telah melihat keberhasilan terbesar dalam penyebaran pelanggan, dan merekomendasikan praktik berikut:

  • Siapkan GitHub atau Azure Repos untuk sistem kontrol kode sumber Anda. Pilihan ini juga akan menentukan pilihan runner alur Anda. GitHub dapat menggunakan Azure Pipelines atau Tindakan GitHub, sedangkan Azure Repos harus menggunakan Azure Pipelines.
  • Siapkan layanan Azure API Management untuk setiap pengembang API sehingga mereka dapat mengembangkan definisi API beserta layanan API. Gunakan SKU konsumsi atau pengembang saat membuat layanan.
  • Gunakan fragmen kebijakan untuk mengurangi kebijakan baru yang perlu ditulis pengembang untuk setiap API.
  • Gunakan nilai dan backend bernama untuk memastikan bahwa kebijakan bersifat umum dan dapat berlaku untuk instans API Management apa pun.
  • Gunakan Azure APIOps Toolkit untuk mengekstrak definisi API yang berfungsi dari layanan pengembang.
  • Siapkan proses persetujuan API yang berjalan pada setiap permintaan pull. Proses persetujuan API harus mencakup deteksi perubahan utama, linting, dan pengujian API otomatis.
  • Gunakan penerbit Azure APIOps Toolkit untuk menerbitkan API ke layanan API Management produksi Anda.

Tinjau Penyebaran API otomatis dengan APIOps di Azure Architecture Center untuk detail selengkapnya tentang cara mengonfigurasi dan menjalankan alur penyebaran CI/CD dengan APIOps.

Referensi