Apa itu OpenAPI?

File OpenAPI, juga dikenal sebagai dokumen OpenAPI atau spesifikasi OpenAPI, memungkinkan pengembang untuk menggambarkan API. Spesifikasi ini juga menjelaskan cara menggunakan API ini, termasuk titik akhir yang tersedia, parameter operasi, metode autentikasi, dan informasi lainnya. Spesifikasi ini ditulis dalam YAML atau JSON, dan skema JSON digunakan untuk menggambarkan format data dalam API.

OpenAPI berfungsi sebagai dokumentasi dan sebagai kontrak (dalam semangat, menjelaskan apa yang harus dilakukan API—tidak mengikat secara hukum) antara konsumen dan produsen API. Ini pada dasarnya berfungsi sebagai “satu sumber kebenaran” yang memberikan instruksi dalam format standar.

Standardisasi ini menyederhanakan konsumsi dan integrasi API. Hal ini memungkinkan manusia dan komputer untuk memahami fungsi dan struktur API tertentu tanpa akses ke kode sumber atau perlu memahami cara kerja internal API. Ini juga memungkinkan pengembang bekerja dengan API, terlepas dari bahasa apa yang ditulis.

OpenAPI mengotomatiskan dokumentasi interaktif dan terkini, menghilangkan beberapa pekerjaan dokumentasi berulang dan membantu memastikan bahwa dokumentasi tetap terkini. OpenAPI juga memungkinkan pembuatan kode untuk SDK klien dan pembuatan kode boilerplate lainnya secara otomatis dari spesifikasi, mengurangi kesalahan manusia dan lebih meminimalkan beban kerja pengembang.

Alat yang menggunakan spesifikasi OpenAPI, termasuk SwaggerUI, dapat merender spesifikasi API dalam antarmuka interaktif. Antarmuka ini tidak hanya membantu memvisualisasikan spesifikasi, tetapi juga memungkinkan panggilan API nyata, langsung dari browser atau layanan web, untuk tujuan pengujian dan validasi.

Dengan menstandardisasi bagaimana REST API dijelaskan, OpenAPI membantu meningkatkan interoperabilitas dan perkakas, serta mendukung operasi di seluruh siklus hidup API. Spesifikasi yang kuat dan terpelihara dengan baik dapat menjadi alat dasar untuk menerapkan strategi API yang komprehensif, mendukung integrasi, kolaborasi, pencegahan kesalahan, dan manajemen API yang lebih kuat.

Spesifikasi lengkap dapat ditemukan di GitHub.

Sebagai standar industri de facto, OpenAPI menyediakan dokumen yang aman, otomatis, dan dipahami secara luas untuk pengembangan API.

OpenAPI awalnya dibuat oleh pengembang Tony Tam dan pertama kali dirilis pada tahun 2011 dengan nama Swagger. Pada saat itu, spesifikasi API sering berupa dokumen statis yang memerlukan pembaruan yang membosankan dan sering kedaluwarsa. Spesifikasi Swagger mencakup beberapa inovasi dalam pengembangan API, termasuk tombol “coba” untuk menguji panggilan API secara langsung dan secara real-time.

Swagger menjadikan dokumentasi sebagai fokus keberadaannya. Swagger memungkinkan pengembang untuk memasukkan anotasi, mirip dengan catatan tempel, ke kode sumber mereka. Swagger dapat membaca anotasi ini dan memperbarui dokumentasi secara otomatis, memastikan bahwa dokumentasi tetap mutakhir tanpa pekerjaan pembaruan yang membosankan dan berulang. Swagger juga memperkenalkan format untuk mendeskripsikan API dalam JSON yang dapat dibaca mesin, yang membuatnya agnostik bahasa: terlepas dari bahasa backend, Swagger akan output file JSON universal.

Swagger diakuisisi oleh SmartBear Software pada tahun 2015, berganti nama menjadi OpenAPI segera setelah itu, dan disumbangkan ke OpenAPI Initiative (OAI) baru, di bawah payung Linux Foundation. Versi saat ini adalah OpenAPI 3.1.

Spesifikasi OpenAPI adalah dokumen standar, dapat dibaca manusia dan mesin yang mendefinisikan struktur dan sintaks API. Semua dokumen OpenAPI menyertakan komponen tertentu dan sesuai dengan struktur dasar yang sama, tetapi beberapa spesifikasi berisi lebih banyak informasi daripada yang lain. Minimal, spesifikasi harus menyertakanopenAPI daninfo bidang, dan setidaknya satupath , component atau webhook bidang.¹

OpenAPI: Catat versi OpenAPI yang digunakan dokumen, seperti “3.1.1”

info: Termasuk metadata API umum, seperti judul API dan nomor versi, deskripsi API, ketentuan layanan, dan informasi kontak. 

server: Daftar URL dasar tempat API dapat diakses (yang mungkin mencakup lingkungan penyiapan dan produksi). Daftar ini mencakup variabel untuk host khusus lingkungan.

path: Menjelaskan jalur dan metode HTTP terkait (atau operasi—misalnya, GET, PUT, POST) dan parameter, badan permintaan, dan respons untuk setiap item jalur.

component: Daftar objek yang dapat digunakan kembali seperti skema data, parameter, respons, header, dan definisi keamanan. Objek-objek ini dapat dirujuk di seluruh dokumen. Komponen dirujuk, cukup sederhana, dengan $ref. Strategi ini membuat desain API sesederhana mungkin. 

security: Menyatakan skema keamanan dan mekanisme autentikasi yang digunakan API, seperti kunci OAuth atau API. Hal ini juga memungkinkan aplikasi skema keamanan secara global, atau dengan operasi.

tag: Daftar tag tingkat tinggi yang digunakan untuk mengatur operasi. Menggunakan tag dapat membantu meningkatkan kejelasan dokumen (misalnya, “Pengguna” atau “Pesanan”).

external documentation: Tautan ke panduan, dokumen orientasi, dan dokumentasi eksternal lainnya untuk API

webhooks: Menjelaskan panggilan masuk yang diterima API. 

OpenAPI menyediakan sumber kebenaran tunggal untuk pengembang dan konsumen API, dan menyediakan fitur yang menambah nilai dan efisiensi untuk proyek API.

OpenAPI awalnya dibuat dengan fokus besar pada dokumentasi untuk REST API, dan fokus itu tetap menjadi intinya saat ini. Dokumentasi distandardisasi, interaktif, diperbarui secara real-time, dan menyediakan kontrak dengan satu sumber kebenaran.

Berbagai alat ada untuk membaca dokumen OpenAPI dan mengekspor kode. Salah satu alat tersebut adalah Swagger Codegen, yang membaca dokumen yang ditulis sesuai dengan spesifikasi OpenAPI. Swagger Codegen kemudian dapat menghasilkan kit pengembangan perangkat lunak kode klien API (SDK), kode sisi server (stub) dan halaman web yang dapat dibaca dengan dokumentasi terkini yang dapat dibaca manusia.

Salah satu fitur OpenAPI yang paling inovatif tetap tombol “coba”, yang memungkinkan pengujian dan validasi real-time langsung dari browser. Swagger UI, alat sumber terbuka gratis, memungkinkan antarmuka visual di mana pengembang dapat mengirim permintaan aktual untuk membantu memastikan bahwa mereka merespons sesuai keinginan. Alat ini memudahkan untuk memverifikasi secara instan bahwa permintaan berfungsi.

OpenAPI umumnya digunakan dengan platform integrasi sebagai layanan, atau iPaaS.

Platform iPaaS menggunakan spesifikasi OpenAPI untuk memahami dan menghubungkan berbagai aplikasi dalam ekosistem TI. Ketika aplikasi mengekspos spesifikasi OpenAPI yang menggambarkan API mereka, platform iPaaS dapat menggunakan informasi ini untuk secara otomatis menemukan titik akhir, metode autentikasi, dan struktur data. Strategi ini membuatnya lebih cepat untuk membangun integrasi, seperti menghubungkan platform e-commerce dengan perangkat lunak akuntansi.

OpenAPI juga memungkinkan pengembang frontend dan backend untuk bekerja secara paralel. Seperti yang kadang-kadang terjadi, pekerjaan paralel lebih disukai oleh tim frontend karena mereka dipaksa untuk menunggu sampai tim backend memiliki database mereka aktif dan berjalan. Dengan kontrak OpenAPI, tim frontend dapat membuat server API tiruan yang berperilaku seperti yang asli, mengaktifkan dan mengoptimalkan pengujian sebelum pengembangan backend selesai. 

Tata kelola API— standar, kebijakan, dan praktik yang mengarahkan bagaimana organisasi mengembangkan dan menggunakan API—sangat penting untuk membantu memastikan bahwa API beroperasi dengan lancar, konsisten, dan tanpa pengulangan yang tidak perlu. Karena OpenAPI bertindak sebagai kontrak di antara pengembang, tata kelola dan keamanan dapat dimasukkan sejak awal.

Ambil API Gateway, yang menangani tugas-tugas seperti perutean lalu lintas, pemantauan, dan pembatasan kecepatan, misalnya. API Gateway biasanya dapat menggunakan spesifikasi OpenAPI dan menegakkan batas lalu lintas atau tindakan keamanan lainnya yang ditetapkan dalam spesifikasi.

Hal yang sama berlaku untuk aturan keamanan. Spesifikasi OpenAPI memungkinkan pengembang mendeklarasikan persyaratan keamanan (seperti penggunaan seperti kunci OAuth 2.0 dan API), dan persyaratan ini dapat diterapkan di hilir (oleh gateway, mungkin.)  Menguraikan fitur keamanan dalam kontrak API membantu memastikan bahwa pengembang tidak melembagakan skema keamanan yang tidak didukung.

OpenAPI dapat memperkuat manajemen API, proses dapat diskalakan untuk membuat, menerbitkan, dan mengelola koneksi API, dalam beberapa cara. Misalnya, karena spesifikasi OpenAPI dapat dibaca mesin dan distandardisasi, katalog dan perangkat lunak portal dapat secara otomatis mengindeksnya. standardisasi ini membuat API lebih mudah ditemukan dan dipahami di seluruh organisasi. Kemampuan untuk ditemukan ini membantu mencegah tim membangun API duplikat secara tidak sadar.

OpenAPI juga mendukung manajemen dan tata kelola yang konsisten dengan membuat standar organisasi eksplisit dan dapat ditegakkan. Tim dapat menentukan persyaratan, seperti konvensi pembuatan versi, format respons kesalahan atau pola penamaan, langsung di dalam atau di samping spesifikasi. Karena ekspektasi ini didokumentasikan dalam format standar, mereka dapat divalidasi secara otomatis terhadap API baru saat ditambahkan. Validasi ini mengurangi ketergantungan pada ulasan manual dan membantu memastikan bahwa API tetap konsisten seiring pertumbuhan portofolio organisasi.