Selama satu setengah tahun, kami mengintegrasikan API dengan dua puluh layanan eksternal. Lima integrasi pertama mengalami rasa sakit dan air mata - kami membuat semua kesalahan yang mungkin. Mereka menulis ulang kode beberapa kali, berpisah dengan mitra sebelum rilis, karena mereka tidak bisa menyetujui perbaikan. Kehilangan waktu dan uang.
Tetapi dengan setiap integrasi baru, kami menemukan solusi untuk masalah yang berulang. Hasilnya, kami membuat integrasi terakhir empat kali lebih cepat dari yang pertama. Apa yang sekarang kita lakukan berbeda - baca artikel.
Agar Anda lebih memahami spesifik dari integrasi kami, kami akan menjelaskan secara singkat apa yang kami lakukan. Kami sedang mengembangkan broker online. Prinsip kerja: pengguna datang ke situs, mengisi kuesioner, kami mentransfernya ke organisasi keuangan mikro (LKM) dan menerima persetujuan atau penolakan dari mereka untuk pinjaman. Pengguna memilih penawaran yang sesuai dan menerima uang. Agar ini berfungsi secara online, kami mengintegrasikan dengan LKM melalui API.
Nilai kesiapan mitra untuk integrasi menggunakan daftar periksa dan spesifikasi
Kami akan menganalisis dua skenario: ketika calon mitra sudah memiliki API untuk menerima aplikasi, dan ketika tidak. Kedua skenario menyarankan bahwa mitra ingin berintegrasi dengan kami dan siap untuk menghabiskan waktu dalam hal ini.
Mitra tidak memiliki API - kami mengirim spesifikasi
Sebelumnya, kami menjelaskan kepada mitra, secara lisan atau korespondensi, apa yang kami butuhkan untuk integrasi, dan mitra berdasarkan penjelasan ini membuat API untuk menerima aplikasi dengan Finspin. Kami tidak menyetujui persyaratan untuk model, objek, bidang kuesioner, dan aturan validasinya. Dengan cepat menggambarkan tujuan dari metode dan jawaban yang mungkin. Hasilnya ternyata jauh dari apa yang diharapkan, karena pemahaman kami tentang API sangat berbeda dari kemitraan. Saya harus mengulang semuanya.
Sekarang Kami menulis spesifikasi kami - file YAML yang dapat dibuka di Swagger. Dalam spesifikasi, kami menggambarkan API yang paling cocok untuk mengintegrasikan Finspin dengan LKM: bidang kuesioner dan aturan validasinya, format permintaan, dan jawaban dengan jawaban, nama metode, kemungkinan kesalahan dan status. Kami mencatat status keadaan aplikasi yang akan kami terima, misalnya: "diterima untuk diproses", "penilaian sedang berlangsung", "ditolak pinjaman", "persetujuan", dll.
Kami mengirim spesifikasi ke mitra, dan dia memutuskan apakah dia bisa menyediakan API semacam itu. Jika tidak bisa, catat poin-poin bermasalah dalam spesifikasi, misalnya, tidak semua negara aplikasi siap untuk ditransfer ke API atau tidak ada cukup bidang dalam kuesioner. Dan kita sudah membahas poin-poin spesifik, bukan entitas abstrak. Mitra tidak membuang waktu menulis dokumentasinya, tetapi menyesuaikan milik kami.
Kami menghabiskan dua hari membuat spesifikasi, tetapi sekarang kami menghemat puluhan jam untuk persetujuan dan peningkatan API. Juga, dengan bantuan spesifikasi, kami dengan cepat menyaring mitra yang tidak siap untuk integrasi. Pada tahap awal, menjadi jelas bahwa proses pemrosesan aplikasi online kami sangat berbeda: tidak menguntungkan untuk diintegrasikan.
Mitra memiliki API - jalankan melalui daftar periksa
Kami
biasa mendapatkan spesifikasi mitra dan mengajukan pertanyaan saat bepergian. Seringkali mereka lupa untuk mengklarifikasi sesuatu yang penting, dan kemudian hal ini muncul pada tahap akhir pengembangan dan pengujian, ketika menjadi sangat mahal untuk diperbaiki dan ditulis ulang. Entah bagaimana, pada akhir integrasi dengan satu mitra, ternyata ia akan mentransfer status pinjaman melalui API dengan penundaan selama beberapa hari. Bagi kami, ini tidak dapat diterima. Kemitraan harus ditinggalkan.
Sekarang Kami telah menulis daftar periksa untuk mengevaluasi API dan proses yang dilayaninya. Daftar periksa mengumpulkan pertanyaan yang harus dijawab. Pertama, manajer kami mencari jawaban dalam spesifikasi. Jika tidak ditemukan, berikan pertanyaan kepada mitra.
Daftar periksa membantu Anda menemukan hambatan sebelum memulai pengembangan, dan bukan setelah - ketika Anda harus mengedit kode dan pelanggan menderita dari layanan yang buruk.
Kami terus-menerus mengisi daftar periksa ketika kami dihadapkan dengan situasi baru. Semakin rinci daftar periksa, semakin rendah risiko melewatkan kesalahan dalam pengembangan.
Fragmen daftar periksa APIDaftar Istilah
Sebelumnya, tampak bagi kami bahwa di bidang peminjaman online setiap orang memahami istilah-istilah profesional dengan cara yang sama, tidak ada perbedaan. Latihan telah menunjukkan bahwa kami salah.
Sebagai contoh, dengan satu LKM, kami menafsirkan klien utama dan klien yang berbeda. Bagi kami, pelanggan utama adalah pelanggan yang profilnya pertama kali memasuki database LKM melalui Finspin, dan pelanggan tetap sudah ada dalam database. Mitra dianggap pelanggan tetap dengan jumlah pinjaman yang dikeluarkan: ulangi menerima dua pinjaman dan datang untuk yang ketiga. Kebingungan terminologis semacam itu dapat menyebabkan inkonsistensi dalam rekonsiliasi keuangan.
Sekarang kami menggunakan daftar istilah kecil yang kami gunakan untuk memeriksa dengan mitra. Sebagai aturan, cukup untuk memperjelas lima atau enam istilah dasar untuk menyinkronkan gagasan tentang integrasi dan menilai prospek untuk kolaborasi.
Setelah daftar istilah membantu kami menghindari integrasi yang tidak menguntungkan. Interpretasi kami tentang "persetujuan" sangat berbeda dari afiliasi. “Persetujuan” mitra mencakup banyak aspek berbeda yang membutuhkan pemrosesan manual. Kami mengusahakan otomatisasi maksimum, jadi kami segera menolak untuk bekerja sama.
Klarifikasi istilah "Persetujuan"Bisnis pertama, lalu pengembangan
Dulu ada kasus ketika kami mulai bekerja dengan mitra potensial dengan spesifikasi. Manajer kami menerima spesifikasi, mempelajarinya dengan seksama, detail yang ditentukan untuk integrasi dengan mitra, membahas masalah yang disengketakan dengan para pengembang. Dan kemudian sebuah pesan datang dari pimpinan: "Akhir, integrasi dibatalkan, kami tidak menyetujui persyaratan." Karyawan membuang waktu.
Ketika Anda berubah pikiran, dan pekerjaan selesaiSekarang aturan besi berlaku: manajer mulai mempelajari spesifikasi hanya ketika dia menerima keputusan yang jelas tentang integrasi dari manajemen.
Kesiapan untuk integrasi: url, detail, lingkungan
Sebelumnya, panggilan pertama ke API mitra terjadi selama pengujian aplikasi kami, dari server dev. Seringkali permintaan pertama menerima kesalahan pada tahap pengaturan koneksi: tidak dapat terhubung ke server atau hanya timeout. Alasan paling populer:
- Nama metode salah (disegel atau bingung)
- Domain tidak valid
- rincian koneksi yang salah,
- Kami tidak menambahkan IP server kami ke daftar putih.
Butuh berjam-jam untuk memperbaiki kesalahan kecil seperti itu, karena kesalahan itu berurutan: sampai Anda memperbaikinya, Anda tidak akan melihat yang berikutnya.
Sekarang , sebelum memasukkan tugas ke dalam rencana pengembangan, kami mengklarifikasi semua fitur mengakses API dengan daftar periksa kecil. Daftar periksa mencantumkan poin-poin yang perlu diklarifikasi, misalnya:
- pembatasan pada beban layanan,
- jumlah permintaan per satuan waktu
- rincian koneksi
- daftar putih dengan alamat ip,
- Validasi sertifikat SSL
- persyaratan enkripsi lalu lintas,
- tajuk khusus dalam permintaan
- keberadaan server pengujian dengan API atau kemampuan untuk mengirim permintaan pengujian ke server tempur
Jika ada API uji, kami pasti akan mencari tahu apa bedanya saat mengakses server pertempuran dan yang uji. Kami memperhitungkan perbedaan akun saat membangun permintaan dari aplikasi kami ke mitra di lingkungan pengembang dan pengembang. Langkah-langkah tersebut membantu kita untuk memahami apakah sistem siap untuk kebutuhan kita atau apakah penyesuaian tambahan diperlukan.
Mengirim permintaan ke API secara manual
Sebelumnya, kami langsung menulis kode sesuai spesifikasi mitra, menyusun spesifikasi, direvisi, diuji. Dan pada tahap pengujian integrasi, ternyata tidak semua yang tertulis dalam spesifikasi sesuai dengan kenyataan - mulai dari format permintaan, berakhir dengan proses pengajuan aplikasi.
Misalnya, menurut spesifikasi, saat mengakses metode tertentu, kami mengharapkan respons dalam format tertentu dalam respons, menutup proses untuk validitas respons yang diterima, pergi ke tes, dan tiba-tiba kami mendapatkan larik dalam respons. Kami mencari tahu alasan dari pengembang mitra. Mereka merujuk pada dokumentasi yang sudah ketinggalan zaman. Sekali lagi, lingkaran perbaikan, ulasan dan tes.
Sekarang , segera setelah kami menerima dokumentasi dan detail koneksi, kami menjalankan proses melalui klien API. Biasanya, penguji mengunggah spesifikasi ke Postman dan mensimulasikan proses bisnis lengkap untuk mengirim aplikasi pinjaman, memeriksa kasus-kasus paling populer dengan set data yang berbeda untuk permintaan tersebut. Artinya, secara manual melakukan apa yang akan dilakukan aplikasi.
Pada tahap menjalankan manual, 80% ketidakakuratan dalam dokumentasi terungkap. Kami menjelaskan kesalahan dan meneruskannya ke mitra. Mitra baik menghilangkan ketidakakuratan di rumah, atau menyelesaikan spesifikasi. Akibatnya, pada saat pekerjaan pada kode dimulai, pengembang menerima dokumentasi yang berfungsi.
Perbedaan paling populer:
- format permintaan yang salah, berjanji untuk menerima json, ternyata membutuhkan formulir-data;
- Kesalahan dalam nama bidang yang akan dikirim dalam permintaan;
- kesalahan dalam format bidang;
- aturan validasi lapangan tidak ditentukan atau ditunjukkan secara tidak benar;
- beberapa bidang mungkin dilupakan sama sekali;
- hilang atau berbeda dari deskripsi aktual dari format respons dari metode;
- tanda yang salah tentang bidang wajib - “tanda bintang” dapat muncul di mana bidang tersebut tidak wajib pada kenyataannya, dan sebaliknya;
- sering tidak mendokumentasikan semua negara bagian dan status tempat objek tersebut berada;
- perbedaan antara keadaan objek yang diharapkan dan yang diterima. Sebagai contoh, di beberapa titik, kami berharap bahwa aplikasi harus dalam keadaan X - dan oleh API, pada kenyataannya, kami mendapatkan Y.
Resep untuk Kebahagiaan: Menghindari Kesalahan Integrasi API
Tulis spesifikasi untuk integrasi dengan layanan Anda. Kami menghabiskan dua hari mengembangkan spesifikasi dalam YAML, tetapi sekarang kami menghemat puluhan jam untuk peningkatan dan persetujuan.
Jika mitra mengirim spesifikasinya, periksa di daftar periksa. Dalam daftar periksa, kumpulkan pertanyaan yang harus Anda terima jawabannya. Jangan mengandalkan pengalaman dan memori, masih ketinggalan sesuatu.
Miliki daftar istilah untuk menghindari kebingungan dengan pasangan Anda. Pengalaman kami telah menunjukkan bahwa perbedaan bahkan bisa dalam istilah yang jelas.
Jangan mengambil tugas dalam pengembangan sampai Anda menerima persetujuan prinsip dari manajemen integrasi dengan mitra. Idenya jelas, tetapi membantu kita menghindari pekerjaan yang tidak perlu.
Buka daftar periksa untuk memperjelas spesifikasi mengakses API mitra: detail koneksi, daftar putih, validasi sertifikat SSL, persyaratan enkripsi lalu lintas, dll. Periksa daftar periksa sesegera mungkin untuk menghindari selip pada tahap akhir.
Mendapat spesifikasi - jangan segera menulis kode. Pertama, jalankan proses secara manual melalui klien API, misalnya, melalui tukang pos. Jadi, Anda akan menemukan kesalahan dalam spesifikasi pada tahap awal dan dengan sumber daya kecil. Dan mereka akan menjadi.