5 Langkah untuk membuat api yang sukses

Ini adalah sifat pengembangan perangkat lunak. Pengembang membuat perangkat lunak dengan mempertimbangkan pengguna akhir. Tampaknya cukup sederhana, tetapi kadang-kadang para pengguna juga sesama pengembang. Mereka tidak perlu hal-hal yang rusak untuk mereka. Mereka bahkan tidak perlu kesederhanaan. Yang mereka inginkan adalah akses - cara untuk mengintegrasikan perangkat lunak Anda dengan perangkat lunak mereka. Di sinilah API (antarmuka pemrograman aplikasi) masuk, saya berharap untuk menyoroti lima langkah yang dapat Anda ambil untuk membuat API yang sukses.

Kerjakan pekerjaan rumah Anda

Ketika datang ke pengembangan perangkat lunak, tidak satupun dari kita ingin menemukan kembali roda. Pada titik ini, hampir semua perusahaan Web besar memiliki API untuk produk perangkat lunak mereka. Pelajari API ini dan cobalah untuk mengambil keputusan desain berbeda yang digunakan untuk membuatnya.

Ada banyak teknologi berbeda di luar sana, tetapi sebagian besar API yang akan Anda lihat akan menggunakan antarmuka RESTful, atau SOAP. Jika Anda berada di pagar untuk antarmuka API mana yang akan Anda gunakan, saya akan menyarankan pergi dengan pendekatan RESTful menggunakan protokol HTTP. Ini lebih sederhana daripada SOAP, saat ini lebih populer, dan akan lebih mudah untuk memulai ketika menggunakan produk perangkat lunak berbasis web.

Konsisten

Salah satu hal yang paling dihargai pengembang adalah konsistensi. Ini termasuk, antara lain, addressability, argumen input, format output dan penanganan kesalahan.

Saat menggunakan pendekatan RESTful, ada banyak skema penamaan URI. Masing-masing memiliki pendukungnya, jadi pilih saja dan pertahankan. Hal yang sama berlaku dengan struktur input dan output. Sebagian besar API mendukung penggunaan XML dan JSON sebagai format input dan output. Saya akan menyarankan mendukung keduanya, tetapi memilih format default.

Untuk input, persyaratan input Anda harus dinamai secara konsisten dan masuk akal dalam konteks panggilan API yang Anda buat. Untuk output, pastikan Anda menggunakan tata letak struktur data umum. Jika Anda membungkus output dari satu panggilan API dalam a Tag XML, pertimbangkan untuk melakukannya dengan panggilan Anda yang lain.

Ini adalah praktik umum untuk memasukkan semacam flag status dalam data output yang Anda kirim kembali ke klien. Saat menggunakan pendekatan API RESTful, ini harus dilakukan menggunakan kode status HTTP. Misalnya, jika Anda baru saja memproses permintaan PUT pada objek data yang ada, kode status HTTP yang Anda sertakan dalam respons Anda akan bervariasi tergantung pada hasil permintaan.

Alih-alih tanda sembarang yang menunjukkan status panggilan, kode status "200 OK" standar dapat digunakan untuk menandakan bahwa permintaan berhasil, sementara kode status "400 Permintaan Buruk" dapat digunakan untuk menandakan bahwa permintaan tersebut cacat. Ada beberapa kode status HTTP yang dapat digunakan dalam situasi yang berbeda.

Gunakan OAuth

Sebagian besar produk perangkat lunak akan melibatkan semacam otentikasi pengguna untuk mengakses sumber daya yang dilindungi untuk pengguna itu. Ketika datang ke API, meminta klien mengumpulkan kredensial pengguna untuk dikirim ke server Anda adalah praktik yang buruk. Di sinilah OAuth masuk

OAuth memberikan banyak manfaat dibandingkan otentikasi nama pengguna / kata sandi pihak ketiga. Yang terpenting, klien tidak pernah memiliki akses ke kredensial pengguna. Pengguna dialihkan ke server Anda ketika dia login. Setelah pengguna masuk ke situs Anda, ia akan diarahkan kembali ke klien di mana klien akan menerima token akses untuk digunakan dalam permintaan di masa depan untuk sumber daya yang dilindungi.

Manfaat penting lain dari menggunakan OAuth adalah kemampuan pengguna untuk membatalkan akses klien setiap saat. Jika pengguna memutuskan bahwa, untuk alasan apa pun, mereka tidak lagi ingin klien dapat mengakses sumber daya yang dilindungi atas nama mereka, mereka hanya pergi ke antarmuka yang Anda buat dan membatalkan akses klien.

Mulai Dini

Salah satu hal terpenting yang dapat Anda lakukan untuk membuat API Anda sukses adalah memulai lebih awal. Saat Anda menulis fungsi itu untuk membuat beberapa entri dalam database Anda, silakan dan luangkan waktu ekstra dan tulis antarmuka API untuknya.

Tulis Dokumentasi yang Baik

Tidak ada yang membunuh API lebih cepat daripada tidak memiliki dokumentasi yang baik. Sementara beberapa pengembang dapat mengambil API yang tidak terdokumentasi dengan baik dan mencari tahu bagaimana itu seharusnya bekerja, sebagian besar tidak mau.

Anda harus mendokumentasikan setiap panggilan API yang Anda miliki dan mengelompokkan panggilan API berdasarkan jenis data yang ditindaklanjuti. Bersamaan dengan mendokumentasikan titik akhir untuk panggilan API sendiri, Anda harus secara sistematis mendefinisikan argumen input yang diperlukan dan opsional serta struktur data output. Argumen input harus mencantumkan nilai default jika ada, dan juga menunjukkan format data yang diharapkan seperti angka atau string. Terakhir, setiap panggilan API harus memiliki daftar kondisi kesalahan dan kode status.

Untuk melengkapi dokumentasi Anda, pastikan untuk memasukkan satu atau dua contoh untuk skenario input dan output yang umum untuk setiap panggilan API.

Pengembangan API: Keep It Simple

Meskipun tampaknya mengembangkan API adalah upaya yang rumit, gagasan tentang API itu sendiri bukanlah konsep baru dan ada sejumlah besar dokumentasi yang tersedia tentang setiap topik yang kami bahas di sini. Pastikan untuk menggunakan praktik yang baik di mana Anda dapat menemukannya, dan untuk menyediakan antarmuka yang konsisten dan terdokumentasi dengan baik.