Apa itu desain API?

Desain API mencakup keputusan tentang titik akhir API, format permintaan dan respons, protokol, dan cara API berkomunikasi dengan aplikasi dan konsumen lain. Desain API juga memegang peran penting dalam tata kelola API.

Tata kelola API mengacu pada seperangkat standar, kebijakan, dan praktik komprehensif yang mengarahkan bagaimana organisasi mengembangkan, menerapkan, dan menggunakan API. Desain API yang efektif menghasilkan API yang mematuhi kebijakan yang telah ditentukan ini, dengan dokumentasi yang kuat dan terkini yang menjelaskan cara kerja API. Hasilnya adalah API yang dirancang dengan baik yang memiliki kegunaan kembali, skalabilitas, serta kompatibilitas yang lebih baik, dan memberikan pengalaman yang lebih baik bagi pengguna akhir mereka.

Ada banyak contoh penggunaan API yang berbeda dan berbagai pendekatan untuk desain API, dengan beberapa protokol, gaya arsitektur, dan bahasa yang lebih cocok untuk tugas atau contoh penggunaan tertentu daripada yang lain.

Seiring dengan meningkatnya penggunaan API web, hal ini telah mengarah pada pengembangan dan penggunaan protokol, gaya, standar, dan bahasa tertentu. Struktur ini menyediakan seperangkat parameter, atau spesifikasi API, yang mendefinisikan jenis data yang diterima, perintah, sintaksis, dan banyak lagi kepada pengguna. Pada dasarnya, protokol API ini memfasilitasi pertukaran informasi yang ter standardisasi.

Protokol, gaya arsitektur, dan bahasa yang umum termasuk:

• SOAP (protokol akses objek sederhana)
• Panggilan prosedur jarak jauh (RPC)
• WebSocket
• REST (transfer negara representasional)
• GraphQL

Memilih struktur yang benar untuk API baru adalah aspek penting dari proses desain. Protokol, gaya arsitektur, dan bahasa ini tidak selalu lebih baik atau lebih buruk antara satu dengan yang lain. Mereka adalah alat yang berbeda untuk tugas yang berbeda.

SOAP adalah spesifikasi protokol pesan berbasis XML ringan yang memungkinkan titik akhir untuk mengirim dan menerima data melalui berbagai protokol komunikasi termasuk SMTP (protokol transfer surat sederhana) dan HTTP (protokol transfer teks). SOAP bersifat independen, yang memungkinkan SOAP API untuk berbagi informasi antara aplikasi atau komponen perangkat lunak yang berjalan di lingkungan yang berbeda atau ditulis dalam bahasa yang berbeda.

Dibandingkan dengan jenis API lainnya, API SOAP cenderung dikembangkan dengan cara yang lebih formal dan terstruktur. API SOAP sudah ada sejak tahun 1990-an; ini merupakan format yang lebih lama dan lebih mapan, tetapi juga lebih lambat daripada arsitektur yang lebih modern seperti REST. 

SOAP bekerja dengan mengenkode data dalam format XML dan tidak mendukung transfer data dalam format lain. Di sisi lain, SOAP API tidak memerlukan HTTP untuk membawa pesan, sehingga memberikan fleksibilitas yang lebih besar dalam memindahkan data. SOAP dianggap lebih aman daripada beberapa protokol lain, sehingga membuat API SOAP sesuai untuk sistem yang menangani data sensitif.

Remote procedure call (RPC) adalah protokol yang menyediakan paradigma komunikasi tingkat tinggi yang digunakan dalam sistem operasi. RPC mengimplementasikan sistem komunikasi klien-ke-server logis yang dirancang khusus untuk mendukung aplikasi jaringan. Protokol RPC memungkinkan pengguna untuk bekerja dengan prosedur jarak jauh seolah-olah prosedur tersebut bersifat lokal1 Hal ini membuat solusi ini cocok untuk situasi yang membutuhkan banyak interaksi klien/server dan interaksi klien/server.

API RPC dapat dipecah lebih lanjut menjadi XML-RPC, JSON-RPC, dan gRPC. XML-RPC adalah panggilan prosedur jarak jauh yang menggunakan format XML tertentu untuk mentransfer data. Alat ini lebih lama ada dari API SOAP, tetapi sederhana dan ringan. JSON-RPC adalah panggilan prosedur jarak jauh yang menggunakan JSON (JavaScript Object Notation) untuk mentransfer data. Karena JSON menggunakan struktur data universal, JSON dapat digunakan dengan bahasa pemrograman apa pun. 

gRPC adalah kerangka kerja RPC sumber terbuka berkinerja tinggi yang awalnya dikembangkan oleh Google. gRPC menggunakan protokol jaringan HTTP/2 dan format data Protocol Buffers dan umumnya digunakan untuk menghubungkan layanan dalam arsitektur layanan mikro.

WebSocket API memungkinkan komunikasi dua arah antara klien dan server. Jenis API ini tidak memerlukan koneksi baru untuk dibuat untuk setiap komunikasi—setelah koneksi dibuat memungkinkan pertukaran berkelanjutan. Hal ini membuat Web Socket API ideal untuk komunikasi real-time. 

Obrolan langsung, pelacakan lokasi waktu nyata, dan penyiaran data adalah contoh penggunaan yang sangat cocok untuk API WebSocket. API WebSocket juga berguna untuk sinkronisasi data, yang merupakan praktik menjaga data tetap konsisten dan mutakhir di beberapa perangkat atau sistem, karena dapat memperbarui secara real time, tanpa perlu membuat koneksi baru setiap kali ada perubahan.

REST adalah seperangkat prinsip arsitektur API web. REST API—juga dikenal sebagai RESTful API—adalah API yang mematuhi batasan arsitektur REST tertentu. REST API menggunakan metode HTTP seperti GET, PUT, HEAD, dan DELETE untuk berinteraksi dengan sumber daya. REST membuat data tersedia sebagai sumber daya, dengan setiap sumber daya diwakili oleh URI unik. Klien meminta sumber daya dengan menyediakan URI-nya. REST API bersifat stateless—mereka tidak menyimpan data klien di antara permintaan.

RESTful API populer karena ringan, fleksibel, dan mudah digunakan. Mereka sepenuhnya mendukung transportasi pesan dalam berbagai format—seperti teks biasa, HTML, YAML, XML, dan JSON—dan mereka juga mendukung caching. Meskipun hal ini membuatnya berguna dalam berbagai macam konteks, beberapa stasiun memerlukan bahasa atau protokol yang lebih spesifik untuk menyelesaikan tugas secara efisien.

GraphQL adalah bahasa kueri dan waktu proses API yang dikembangkan secara internal oleh Facebook pada tahun 2012 sebelum menjadi sumber terbuka pada tahun 2015. GraphQL memungkinkan pengguna untuk membuat permintaan API hanya dengan beberapa baris, daripada harus mengakses titik akhir yang kompleks dengan banyak parameter. Kemampuan ini dapat memudahkan untuk menghasilkan dan merespons kueri API, terutama permintaan yang lebih kompleks atau spesifik yang menargetkan banyak sumber daya.

Dengan mempertimbangkan bahwa Meta mengembangkan bahasa kueri ini untuk membuat aplikasi mobile mereka lebih efisien, masuk akal bahwa GraphQL API berguna untuk aplikasi mobile. Dengan menawarkan satu titik entri, API GraphQL dapat menurunkan waktu pemuatan dengan melakukan kueri data tanpa harus membuat banyak permintaan ke server. 

Ada empat tahap utama dari proses desain untuk API:

• Rencana
• Mengembangkan
• Tes
• Menyebarkan

Semua langkah ini memerlukan kolaborasi antara pemangku kepentingan API utama. Meskipun beberapa langkah lebih cocok untuk beberapa pemangku kepentingan daripada yang lain, desain API tetap harus bersifat kolaboratif selama proses berlangsung. Hal ini membantu pengembang menghindari penambahan fungsi tambahan yang tidak diperlukan program, sehingga mempercepat proses pengembangan secara keseluruhan.

Langkah pertama dari proyek apa pun adalah membuat semua orang sepakat tentang jenis API baru apa yang mereka buat. API sisi publik yang ditujukan bagi pelanggan untuk berinteraksi dengan dalam pengaturan e-commerce memiliki kebutuhan desain dan fungsi yang berbeda dari yang dimaksudkan untuk digunakan secara internal untuk alur kerja autentikasi; penting bagi semua pemangku kepentingan untuk memahami contoh penggunaan untuk API potensial sebelum pengembangan dimulai.

Memahami apa yang dibangun oleh sebuah perusahaan (dan alasannya) dapat membantu pengembang menemukan cara yang lebih baik untuk membuatnya, termasuk protokol apa yang digunakan. Jika, misalnya, API potensial ini membutuhkan komunikasi real-time, maka pengembang tahu bahwa mereka dapat menggunakan WebSocket saat membuatnya karena protokol tersebut sangat cocok untuk tujuan tersebut. 

Setelah para pemangku kepentingan memiliki visi yang jelas tentang API yang akan dibuat dan cara kerjanya, saatnya untuk mulai membuat. Selama proses pengembangan API, pengembang mendefinisikan titik akhir API; merancang model data untuk API; memastikan bahwa API mematuhi kebijakan keamanan API dan mengembalikan kode status standar untuk kesalahan; jika perlu, mengimplementasikan mekanisme autentikasi seperti header HTTP, kunci API, OAuth, atau JSON Web Token (JWT); mendefinisikan kode kesalahan, pesan, dan respons.

Bagian lain dari proses pengembangan adalah dokumentasi. Ketika API dalam proses pembuatan, semua pilihan yang dibuat harus ditangkap dalam dokumen yang dapat dibaca oleh manusia dan mesin. Dokumen yang dapat dibaca manusia ditulis dalam bahasa yang alami dan mudah dipahami. Dokumen yang dapat dibaca mesin harus mengikuti spesifikasi API, seperti spesifikasi OpenAPI, yang menstandarkan format sehingga konsisten dan dapat diintegrasikan ke dalam sistem di masa mendatang.

Desain API dapat menjadi proses yang perlu banyak pengulangan; terutama jika API mengekspos data sensitif, penting untuk mengujinya secara ketat untuk menemukan bug dan kekurangan. Setelah membangun sesuatu, penting untuk melihat apakah fungsinya berjalan sebagaimana mestinya. Bagian penting dari pengujian API adalah membuat mockup, yang merupakan proses pembuatan server tiruan dengan data sampel untuk memeriksa apakah API berkomunikasi dengan titik akhir secara tepat dan menampilkan hasil yang diharapkan. 

Proses mockup dapat dilakukan bersamaan dengan pengujian API. Pengujian API meliputi pengujian kontrak, yang menetapkan seperti apa permintaan dan respons yang seharusnya; pengujian unit, yang mengonfirmasi bahwa satu titik akhir memberikan respons yang diharapkan; pengujian beban, yang menguji apakah API dapat berkinerja dalam lalu lintas puncak dan pengujian ujung ke ujung, yang memvalidasi perjalanan pengguna yang melibatkan komunikasi dengan lebih dari satu API. Pengujian dapat dilakukan secara manual, atau dengan menerapkan kerangka kerja otomatis.

Jika semuanya berfungsi sebagaimana mestinya, maka API siap untuk dirilis dan diterapkan. Pada saat ini, dokumentasi API harus sudah diselesaikan sehingga pengguna lain dan mesin mereka dapat mengintegrasikan API ini dengan benar ke dalam lingkungan jaringan komputer mereka. Ada kemungkinan bahwa setelah API dirilis, pengguna menemukan masalah dengannya yang tidak diantisipasi oleh pemangku kepentingan. Sangat membantu untuk memiliki strategi pembuatan versi sebelum API dirilis sehingga jika pengembang perlu memperbarui aplikasi, prosesnya dapat dilakukan dengan jelas dan konsisten.

Pendekatan yang mengutamakan API untuk pengembangan aplikasi memprioritaskan merancang API di awal proses pengembangan perangkat lunak dan membangun aplikasi dengan layanan yang akan dikirimkan melalui API. Idenya adalah dengan memprioritaskan desain API di awal pengembangan perangkat lunak, API yang dihasilkan akan lebih mudah digunakan kembali, aman, efisien, lebih mudah digunakan, dan lebih selaras dengan tujuan organisasi. Pendekatan ini berlawanan dengan pendekatan mengutamakan kode, yang mengutamakan logika kode, dengan pengembang membuat API untuk dimasukkan ke dalam perangkat lunak nantinya. 

Desain API adalah kunci dalam pendekatan yang mengutamakan API. Dalam pendekatan yang mengutamakan API, API menjadi pusat pengembangan aplikasi dan desain yang dipertimbangkan dengan baik akan mendorong pengembangan aplikasi yang berkinerja lebih baik dan lebih bernilai. 

Praktik desain API yang kuat juga dapat membantu meningkatkan pengalaman pengembang dan pengalaman pengguna akhir dengan menemukan dan menyelesaikan hambatan pengembangan dan kinerja sebelum berubah menjadi masalah yang lebih besar.

Pemangku kepentingan dapat menetapkan sejak awal proses pengembangan bahwa semua aplikasi perusahaan terintegrasi dan bersinergi satu sama lain. Ketika berhasil diimplementasikan, pendekatan yang mengutamakan API dengan dokumentasi yang komprehensif memungkinkan pengembang untuk menggunakan kembali API yang sudah ada daripada membuat ulang fungsi yang sudah ada.

REST (atau RESTful) API memiliki struktur yang fleksibel. Satu-satunya persyaratan adalah bahwa mereka menyelaraskan diri dengan enam prinsip desain REST berikut ini, yang juga dikenal sebagai batasan arsitektural: Antarmuka yang seragam, pemisahan klien/server, tanpa status, kemampuan cache, arsitektur sistem berlapis dan, secara opsional, kode sesuai permintaan. 

Pembatasan arsitektur ini membuat RESTful API sangat cocok untuk pendekatan yang mengutamakan API: Pemisahan klien/server dan tidak adanya struktur yang kaku sangat membantu. 

Dalam API RESTful, aplikasi klien dan server harus independen satu sama lain. Satu-satunya informasi yang harus diketahui aplikasi klien adalah pengenal sumber daya seragam (URI) dari sumber daya yang diminta; itu tidak dapat berinteraksi dengan aplikasi server dengan cara lain. 

RESTful API juga tidak memiliki status, yang berarti bahwa setiap permintaan harus menyertakan semua informasi yang diperlukan untuk memprosesnya. Dengan kata lain, REST API tidak memerlukan sesi sisi server apa pun. Batasan ini membuat API ini tidak bergantung pada server perusahaan, sehingga menjadikannya fleksibel—aplikasi sisi klien dan server dapat ditulis dengan bahasa dan protokol yang berbeda tanpa memengaruhi desain API.

RESTful API juga cocok untuk lingkungan yang mengutamakan API karena dapat diskalakan dan ringan. Pemisahan antara klien dan server meningkatkan skalabilitas karena RESTful API tidak perlu menyimpan informasi permintaan klien di masa lalu, sehingga mengurangi hambatan komunikasi. Caching yang efektif juga dapat mengurangi interaksi klien/server, ini nilai tambah lain untuk skalabilitas. Karena RESTful API menggunakan format HTTP untuk transportasi pesan, API tersebut dapat menerima transfer data dalam berbagai format. Hal ini dapat menyederhanakan integrasi ke dalam lingkungan baru.

Arsitektur layanan mikro adalah gaya arsitektur cloud-native di mana satu aplikasi terdiri dari banyak komponen atau layanan yang lebih kecil yang digabungkan secara fleksibel dan dapat diterapkan secara independen. REST API sering digunakan untuk memungkinkan komunikasi antara layanan-layanan yang lebih kecil ini.

Pendekatan yang mengutamakan API sangat cocok dengan skema arsitektur layanan mikro karena API digunakan untuk menghubungkan layanan secara bersama-sama. Jika desain API dijadikan prioritas dalam organisasi dan API dirancang untuk berkomunikasi dengan lancar satu sama lain, pengembang menghemat waktu sambil mengemas layanan tersebut bersama-sama ke dalam aplikasi yang lebih besar. 

Untuk mendapatkan nilai paling besar dari API perusahaan, organisasi sering menekankan:

• Tata kelola dan dokumentasi API
• Pengumpulan masukan pemangku kepentingan
• Autentikasi yang tepat
• Penerapan versi
• Standardisasi pesan kesalahan
• Penskalaan dan konteks
• Konsistensi

Prinsip-prinsip ini membantu semua pemangku kepentingan tetap mendapat informasi sepanjang proses desain API dan memastikan bahwa API selaras dengan tujuan dan strategi organisasi.  

Tata kelola dan dokumentasi API: Menetapkan strategi tata kelola dan dokumentasi API di seluruh organisasi sejak dini membantu meningkatkan konsistensi dan membuat portofolio API perusahaan lebih mudah dinavigasi. Sebagai contoh, sebuah organisasi dapat memilih untuk mengadopsi spesifikasi seperti OpenAPI sehingga semua API perusahaan mematuhi standar industri. Dalam hal apa pun, mempertahankan tata kelola dan dokumentasi yang tepat dan konsisten memungkinkan pengguna API baru untuk mendapatkan pemahaman yang cepat tentang API dan fungsinya. 

Mengumpulkan umpan balik pemangku kepentingan: Masukan awal dari pemangku kepentingan inti dan konsumen API membantu membuat pengembang tetap berada di jalur yang benar selama proses pengembangan. Komunikasi yang buruk dapat menyebabkan keterlambatan dalam pengembangan API dan API yang kurang bermanfaat.

Autentikasi yang tepat dan keamanan API: Untuk melindungi API, serta data sensitif, organisasi menerapkan teknik autentikasi yang menyediakan validasi untuk permintaan API. Mekanisme autentikasi seperti kunci API, OAuth, dan JSON Web Tokens (JWT) menyediakan metode yang berbeda untuk mengamankan lalu lintas data dan API. Enkripsi API, proses pengkodean data untuk perjalanan antara klien dan server, juga digunakan untuk melindungi data dan API.

Pengujian dan pembuatan versi: Pengujian API mencakup berbagai skenario, baik positif maupun negatif, untuk mengidentifikasi masalah sebelum API diterapkan. API berkembang selama pengujian ini dan pengembang membuat versi baru yang memperbaiki bug atau meningkatkan kinerja. Versi API baru juga dirilis karena alasan lain, seperti saat developer menambahkan fitur baru ke API. Pembuatan versi adalah cara pengembang mengelola perubahan pada API, membuat perubahan transparan, dan memastikan bahwa pembaruan tidak mengganggu pengguna saat ini.

Akan sangat membantu jika mekanisme pembuatan versi—seperti pembuatan versi berbasis URL atau pembuatan versi berbasis header—didefinisikan sebelum pengembangan benar-benar dimulai.

Standardisasi pesan kesalahan: Penanganan kesalahan yang tepat akan meningkatkan pengalaman konsumen API karena membantu dalam pemecahan masalah ketika terjadi kesalahan. Kode kesalahan, pesan, dan respons harus secara akurat menggambarkan sifat kesalahan dan tetap jelas dan konsisten.

Konteks dan batasan: Setiap API ada dalam konteks tertentu yang menentukan bagaimana API akan dibangun dan apa fungsinya. Tenggat waktu proyek yang bertentangan, volume lalu lintas yang diharapkan, dan apakah perusahaan mengutamakan API atau mengutamakan kode dapat membentuk API yang dihasilkan. Penting bagi semua pemangku kepentingan untuk mengetahui informasi ini agar mereka dapat membuat keputusan yang tepat selama proses pengembangan.

Konsistensi: Yang terpenting, menjaga semuanya tetap konsisten secara umum menciptakan desain API yang lebih baik. Konsistensi dalam desain API lebih dari sekadar versi dan kode kesalahan. Saat menentukan titik akhir, menjaga konvensi penamaan tetap konsisten dapat membuatnya lebih mudah untuk diidentifikasi. Saat membuat permintaan khusus ke API, itu harus diselesaikan dengan cara yang sama setiap saat. Ketika semuanya konsisten di seluruh lingkungan API, maka akan lebih mudah untuk mendokumentasikan API agar dapat dimengerti oleh pengguna di masa mendatang.