Ketika membuat api haruskah saya menggunakan fungsi kecil dan banyak panggilan, atau beberapa panggilan dan fungsi besar?

Saya memiliki platform rel yang saya pelihara. Ini memiliki banyak aplikasi web berbeda yang dibangun di atasnya. Namun sekarang klien meminta API agar mereka dapat menjaga pengguna di situs mereka, tetapi manfaatkan beberapa tugas otomatis yang kami miliki.

Platform ini digunakan untuk membuat aplikasi asuransi dan memungkinkan pembelian secara online, serta menyediakan cara untuk mengunduh dokumentasi yang terkait dengan kebijakan Anda.

Jadi pertanyaan saya ketika membangun API adalah ini:

Ketika saya harus melakukan banyak hal, seperti validate, membuat user, user profiledan policy, cukup banyak pada waktu yang sama. Haruskah saya membuat 4 panggilan API terpisah, dan membuat klien membuat 4 panggilan di sisi mereka. ATAU haruskah saya memiliki satu panggilan yang kecuali banyak parameter, yang memvalidasi klien dan membuat semua 3 hal itu pada saat yang sama, menyederhanakan hal-hal untuk klien?

Klien, dalam hal ini, mendapatkan semua informasi yang diperlukan pada saat yang sama, sehingga tidak seperti ada aliran alami dalam aplikasi mereka di mana ia berhenti dan mereka dapat membuat panggilan API ke platform saya.

Setelah berada di sisi klien menggunakan banyak API sebelumnya, usus saya adalah untuk membuatnya sesederhana mungkin bagi klien dan meminta mereka membuat hanya satu panggilan. Namun ini mengarah ke functionsAPI yang agak besar , yang saya juga bukan penggemar.

Bagaimana Anda menyarankan saya mengatasi ini?

Sebagai catatan, saya tidak terlalu percaya pada kemampuan klien untuk mengimplementasikan API yang rumit di pihak mereka.

Bagaimana kalau melakukan keduanya? Miliki API " level rendah " (bisa dikatakan) yang memaparkan fungsi sistem dan memiliki "lapisan" lain yang memaparkan layanan yang mungkin ingin dilakukan klien. Lapisan ini akan menggunakan API tingkat rendah yang diperlukan tetapi masih terbuka jika klien menginginkannya.

UPDATE: Untuk juga memasukkan beberapa poin besar dan komentar yang dibuat oleh orang lain.

1. Pertimbangkan apakah klien akan perlu memanggil salah satu metode API yang lebih kecil, mis. Apakah layak untuk memanggil createUserProfile tanpa juga memanggil createUser? Jika tidak maka jangan memaparkan metode itu. Terima kasih NoobsArePeople2

2. Poin sederhana namun luar biasa. Poin kunci dengan mengekspos sesuatu dalam API - Anda tidak akan pernah bisa mengeksposnya. Mengekspos minimum yang diperlukan untuk berfungsi dan kemudian berkembang daripada memaparkan segalanya dan ... yah, maka itu telanjang dan membuat perubahan bisa memalukan dan canggung . Terima kasih Michael

Saya pikir Anda melihatnya dengan cara yang salah. Jangan khawatir tentang besar | panggilan kecil atau banyak | beberapa panggilan.

Pikirkan tentang objek bisnis dan tindakan yang dapat dilakukan dengan | untuk | terhadap benda-benda itu.

Kamu sudah memperoleh:

• Pengguna
• Kebijakan
• Tarif
• ...

Jadi, Anda harus membuat panggilan API di sekitar objek tersebut.

• User.Create
• User.UpdatePassword
• Kebijakan. Validasi
• ...

Idenya adalah untuk menciptakan operasi atom atau dekat-atom berdasarkan obyek bisnis dan tindakan mereka. Hal ini akan menyederhanakan desain dan coding - panggilan yang melakukan apa objek bisnis harus melakukan yang cocok dengan model mental atau harapan dari para programer. Ketika programmer atau arsitek membahas persyaratan dengan analis bisnis maka mereka semua bisa menggunakan terminologi yang sama dan aliran umum dari operasi.

Masalah dengan yang lebih besar, all-in-satu jenis panggilan adalah risiko efek samping. Jika Policy.Create juga memunculkan Pengguna dan memicu beberapa tindakan lain, maka itu akan mematahkan harapan para programmer. Demikian juga, banyak panggilan kecil memaksa programmer untuk mengingat untuk memanggil A dan kemudian B dan C untuk melakukan operasi bisnis "tunggal".

Dan bagaimana Anda menyebutkan panggilan akan didasarkan pada Rails apa dan layanan web pendukung Anda akan mendukung.

Agar lebih preskriptif, ini akan membuat beberapa panggilan yang mengambil sejumlah parameter dan mungkin memiliki beberapa panggilan di back-end yang dikaburkan untuk klien. Anda juga akan berakhir dengan beberapa panggilan yang cukup cepat / sederhana di mana API lebih dari sekadar pembungkus untuk rutinitas yang mendasarinya.

Saya pikir firasat Anda benar - buat API mudah bagi konsumen. Sampai batas tertentu, ini adalah filosofi di balik Kontrak yang Didorong Konsumen .

Lebih khusus lagi, API harus mengekspos kasus penggunaan bisnis yang sesuai. Pertimbangkan domain bisnis yang ada - apakah benar-benar ada kebutuhan untuk fungsi-fungsi tingkat rendah itu? Apa kelemahan merangkum mereka? Fungsi-fungsi besar di API bukanlah masalah di dalam dan dari dirinya sendiri. Apa yang akan menjadi masalah adalah jika fungsi besar mengurutkan operasi yang mungkin perlu dipartisi untuk memungkinkan intervensi konsumen.

Secara pribadi, saya suka API yang:

1. dioptimalkan sedemikian rupa sehingga kasus penggunaan umum dapat dengan mudah dilakukan
2. panggilan yang terkait dengan operasi CRUD berorientasi batch atau memiliki versi batch
3. memungkinkan refleksi (sehingga orang yang menulis plugin atau binding untuk bahasa komputer lain dapat mengotomatiskan proses)