5 Langkah untuk mewujudkan api yang berjaya

Ia adalah sifat pembangunan perisian. Pemaju membuat perisian dengan pengguna akhir dalam fikiran. Nampaknya agak mudah, tetapi kadang-kadang pengguna itu juga merupakan pemaju sesama. Mereka tidak memerlukan benda yang rosak untuk mereka. Mereka tidak memerlukan kesederhanaan. Apa yang mereka mahukan ialah akses - cara mengintegrasikan perisian anda dengan mereka. Di sinilah API (antara muka pengaturcaraan aplikasi) masuk, saya berharap untuk menyerlahkan lima langkah yang anda boleh ambil untuk mewujudkan API yang berjaya.

Buat kerja sekolah kamu

Apabila ia datang kepada pembangunan perisian, tiada seorang pun daripada kita mahu mencipta semula roda. Pada ketika ini, hampir semua syarikat web besar mempunyai API untuk produk perisian mereka. Kajian ini API dan cuba mengambil keputusan reka bentuk yang berbeza yang membuat mereka.

Terdapat banyak teknologi yang berbeza di luar sana, tetapi kebanyakan API yang anda akan lihat akan menggunakan sama ada antara muka RESTful, atau SOAP. Sekiranya anda berada di pagar untuk menggunakan antara muka API yang akan digunakan, saya cadangkan pergi dengan pendekatan RESTful menggunakan protokol HTTP. Lebih mudah daripada SOAP, ia kini lebih popular, dan ia akan menjadi lebih mudah untuk memulakan apabila menggunakan produk perisian berasaskan Web.

Selaras

Salah satu perkara yang paling menghargai pemaju adalah konsistensi. Ini termasuk, antara lain, kebolehpasaran, hujah input, format output dan pengendalian ralat.

Apabila menggunakan pendekatan RESTful, terdapat banyak skema penamaan URI yang berbeza. Setiap orang mempunyai penyokongnya, jadi pilih saja dan tahan dengannya. Begitu juga dengan struktur input dan output. Kebanyakan sokongan API menggunakan XML dan JSON sebagai format input dan output. Saya akan mencadangkan sokongan kedua-duanya, tetapi memilih format lalai.

Untuk input, keperluan masukan anda harus dinamakan secara konsisten dan harus masuk akal dalam konteks panggilan API yang anda buat. Untuk output, pastikan anda menggunakan susun atur struktur data biasa. Jika anda membungkus output satu panggilan API dalam a Tag XML, pertimbangkan untuk melakukan itu dengan panggilan lain anda.

Ia adalah amalan biasa untuk memasukkan beberapa jenis bendera status dalam data output yang anda hantar semula kepada pelanggan. Apabila menggunakan pendekatan API RESTful, ini perlu dilakukan menggunakan kod status HTTP. Contohnya, jika anda memproses permintaan PUT pada objek data sedia ada, kod status HTTP yang anda masukkan dalam respons anda akan berbeza-beza bergantung kepada hasil permintaan tersebut.

Daripada bendera sewenang-wenang yang menunjukkan status panggilan, kod status "OK OK" boleh digunakan untuk menandakan bahawa permintaan itu berjaya, sementara kod status "400 Permintaan Buruk" boleh digunakan untuk menandakan bahawa permintaan itu cacat. Terdapat beberapa kod status HTTP yang boleh digunakan dalam situasi yang berbeza.

Gunakan OAuth

Kebanyakan produk perisian akan melibatkan beberapa jenis pengesahan pengguna untuk mengakses sumber yang dilindungi untuk pengguna tersebut. Ketika datang ke API, setelah klien mengumpul bukti kepercayaan pengguna untuk dikirim ke server Anda adalah praktik yang buruk. Di sinilah OAuth masuk.

OAuth menyediakan banyak manfaat ke atas pengesahan nama pengguna / kata laluan pihak ketiga. Di atas semua, pelanggan tidak pernah mempunyai akses kepada kelayakan pengguna. Pengguna diarahkan ke pelayan anda apabila dia log masuk. Selepas pengguna log masuk ke tapak anda, dia akan diarahkan kembali ke klien di mana klien akan menerima token akses untuk digunakan dalam permintaan masa depan kepada sumber yang dilindungi.

Satu lagi manfaat penting menggunakan OAuth ialah keupayaan pengguna untuk membatalkan akses pelanggan pada bila-bila masa. Sekiranya pengguna memutuskan bahawa, atas sebab apa pun, mereka tidak lagi mahu pelanggan dapat mengakses sumber yang dilindungi bagi pihak mereka, mereka hanya pergi ke antara muka yang telah anda buat dan membatalkan akses pelanggan.

Mula awal

Salah satu perkara yang paling penting yang boleh anda lakukan untuk menjadikan API anda kejayaan adalah untuk memulakan lebih awal. Apabila anda menulis fungsi itu untuk membuat beberapa entri dalam pangkalan data anda, teruskan dan ambil masa tambahan dan tulis antara muka API untuknya.

Tulis Dokumentasi Baik

Tidak ada yang membunuh API lebih cepat daripada tidak mempunyai dokumentasi yang baik. Walaupun sesetengah pemaju boleh menggunakan API yang kurang didokumenkan dan memikirkan bagaimana ia sepatutnya berfungsi, kebanyakannya tidak mahu.

Anda harus mendokumentasikan setiap panggilan API yang anda ada dan mengkategorikan panggilan API anda mengikut jenis data yang mereka bertindak. Bersama mendokumentasikan titik akhir bagi panggilan API sendiri, anda perlu menentukan secara sistematik hujah input yang diperlukan dan opsyen serta struktur data output. Hujah input harus menyenaraikan nilai lalai jika terdapat satu, dan juga menunjukkan format data yang diharapkan seperti nombor atau rentetan. Akhir sekali, setiap panggilan API harus mempunyai senarai keadaan ralat dan kod status.

Untuk melengkapkan dokumentasi anda, pastikan anda memasukkan satu atau dua contoh untuk senario input dan output umum untuk setiap panggilan API.

Pembangunan API: Simpan Ia Mudah

Walaupun kelihatannya bahawa membangunkan API adalah usaha rumit, gagasan API itu sendiri bukanlah konsep baru dan terdapat banyak dokumentasi yang tersedia pada setiap topik yang kita sentuh di sini. Pastikan anda menggunakan amalan terbaik di mana anda boleh mencarinya, dan untuk menyediakan antara muka yang konsisten dan didokumenkan dengan baik.