Menulis API - mematahkan XML (dua)

API MyStore pertama muncul 10 tahun yang lalu. Selama ini kami sedang mengerjakan versi API yang ada dan mengembangkan yang baru. Dan beberapa versi API sudah terkubur.

Artikel ini akan memiliki banyak hal: cara membuat API, mengapa layanan cloud membutuhkannya, apa yang memberi pengguna rake apa yang kami kelola dan apa yang ingin kami lakukan selanjutnya.

Nama saya Oleg Alekseev oalexeev , saya adalah direktur teknis dan salah satu pendiri MySklad.

Mengapa membuat API untuk layanan

Pelanggan kami, yang merupakan puluhan ribu pengusaha, aktif menggunakan solusi cloud: perbankan, toko online, akuntansi produk, CRM. Terhubung ke satu - dan sudah sulit untuk berhenti. Dan sekarang layanan kelima, kedelapan, kesepuluh membuat pekerjaan wirausahawan lebih mudah, tetapi pengguna mentransfer data di antara layanan cloud ini secara manual. Pekerjaan berubah menjadi mimpi buruk.

Solusi yang jelas adalah memberi pengguna kemampuan untuk mentransfer data antara layanan cloud. Misalnya, impor dan ekspor data sebagai file, yang kemudian dapat diunduh ke layanan yang diinginkan. File biasanya diubah ke format setiap layanan. Ini lebih atau kurang pekerjaan manual yang sederhana, tetapi dengan meningkatnya jumlah layanan ini, menjadi lebih sulit untuk melakukannya.

Karena itu, langkah selanjutnya adalah API. Dengannya, layanan cloud mendapat manfaat dari menghubungkan beberapa layanan pada satu titik. Munculnya ekosistem seperti itu menarik pelanggan baru karena peluang tambahan. Produk dengan fungsi baru menjadi lebih menguntungkan dan bermanfaat.

Jika Anda membuat antarmuka program Anda sendiri, itu menarik penjual pihak ketiga dalam bentuk programmer yang tahu tentang produk Anda berkat API. Mereka mulai membangun solusi berdasarkan API yang diusulkan dan mendapatkan uang dengan mengotomatiskan tugas-tugas pelanggan mereka.

Sistem akuntansi MyStore dibangun di atas proses sederhana. Hal utama adalah bekerja dengan dokumen primer, kemampuan untuk menerima dan mengirimkan barang, dan menerima laporan bisnis berdasarkan primer. Ada juga transfer data, misalnya, ke cloud accounting, dan penerimaannya dari sistem perbankan atau outlet ritel. Kami juga bekerja dengan toko online: kami menerima informasi tentang barang dan mengirim data tentang saldo.

API MyStore Pertama

Lebih dari 10 tahun MyStore bekerja dengan API, kami telah memperoleh semua jenis integrasi yang memungkinkan Anda untuk bertukar data, bekerja dengan bank, membayar dan menggunakan telepon eksternal.

Pada tahun pertama, kami memungkinkan untuk mengunggah data apa pun dalam format XML. Maka itu jauh lebih dimengerti dan akrab bagi pengguna untuk menyimpan data offline, dan tidak di semacam cloud di sana, dan kami memberi mereka ini. Bongkar dimulai dengan ekspor manual dari antarmuka. Artinya, API belum dapat dipanggil.

Kemudian kami mulai bekerja sama dengan Rusagro - mereka sudah menggunakan ERP "dewasa" untuk merencanakan produksi dan penjualan, tetapi pemuatan mobil di pabrik otomatis di MySklad. Jadi kami mendapatkan dasar pertama dari API ini: pertukaran antara layanan kami dan ERP terjadi dengan mengirimkan file besar dengan data untuk semua jenis dokumen.

Ini adalah pilihan yang baik untuk pertukaran data batch, tetapi bersama dengan dokumen mereka harus mentransfer dependensi mereka: informasi tentang barang, kontraktor dan gudang. Tempat pembuangan seperti itu tidak begitu sulit untuk dihasilkan selama ekspor, tetapi agak sulit untuk dibongkar selama impor, karena semua informasi datang dalam satu paket: baik tentang dokumen baru dan tentang yang sudah ada.

XML API pertama tidak bertahan lama - dua tahun kemudian, kami mulai membangunnya kembali. Bahkan pada awal karyanya, kami membuat beberapa kesalahan ketika membangun antarmuka perangkat lunak.


Bagaimana XML API dibuat: ilustrasi dari salah satu arsitek kami. Ngomong-ngomong, tunggu artikelnya.

Inilah kesalahan utama kami:

1. Markup JAXB dilakukan langsung pada kacang entitas. Kami menggunakan Hibernate untuk berkomunikasi dengan database, dan markup JAXB dibuat pada kacang yang sama. Kesalahan ini segera muncul: setiap pembaruan pada struktur data mengarah pada kebutuhan untuk segera memberi tahu siapa pun yang menggunakan API, atau untuk membangun kruk yang akan memastikan kompatibilitas dengan struktur data sebelumnya.
2. API tumbuh sebagai tambahan, dan pada awalnya kami tidak menentukan bagian produk apa yang dibuatnya. Kami bahkan tidak memikirkan apakah API itu sesuatu yang penting, apakah perlu mempertahankan kompatibilitas ke belakang untuk pelanggan pertama. Pada titik tertentu, jumlah pengguna API adalah sekitar 5% dari total jumlah kecil, dan tidak ada perhatian diberikan kepada mereka. Pemfilteran universal yang dibuat pada waktunya telah menyebabkan kami menjadi digunakan sebagai backend. Pemfilteran ini sama sekali bukan GraphQL, tetapi sesuatu seperti itu - itu berfungsi melalui banyak parameter string kueri. Dengan alat yang sangat kuat, sulit bagi pengguna untuk menolak, dan permintaan dikirim kepada kami sehingga mereka dikirim langsung dari UI toko online mereka. Situasi ini merupakan kejutan yang tidak menyenangkan, karena penyediaan layanan seperti itu harus memerlukan penagihan berbeda dan pemahaman yang berbeda tentang API itu sendiri sebagai produk.
3. Karena fakta bahwa API tidak berkembang sebagai produk utama, dokumentasi API diproduksi dan diterbitkan sesuai dengan prinsip residu - melalui rekayasa balik. Cara ini tampaknya cukup sederhana dan nyaman, tetapi bertentangan dengan pekerjaan kontrak. Ini terjadi ketika ada komponen tertentu dengan skema kerja yang telah ditentukan. Pengembang mengimplementasikannya sesuai dengan skema dan tugas ini, komponen diuji, klien menerima produk yang cocok dengan ide analis. Reverse engineering, di sisi lain, melempar produk yang hanya ada: dengan kruk, solusi aneh dan sepeda alih-alih fungsionalitas yang diperlukan.
4. Seluruh aliran permintaan yang datang melalui API dapat dianalisis tidak lebih dari log Nginx atau server aplikasi. Ini tidak memungkinkan kami untuk mengisolasi area subjek, kecuali mungkin membaginya dengan pengguna dan pelanggan. Jika tidak mungkin untuk mengatur pendaftaran aplikasi atau klien, menjadi tidak mungkin untuk menganalisis situasi. Masalah ini memiliki dampak paling kecil pada pengembangan API, lebih pada memahami relevansi dan fungsionalitasnya.

Percobaan nomor dua: REST API

Pada 2010, kami mencoba membangun sistem pertukaran dengan akuntansi online - BukhSoft. Tidak lepas landas. Tetapi dalam proses integrasi, API lengkap muncul: layanan pertukaran REST, di mana tidak ada kebebasan seperti panggilan ke operasi dalam bentuk panggilan RPC. Semua komunikasi dengan API dibawa ke mode standar untuk istirahat: string kueri berisi nama entitas, dan operasi yang dilakukan dengannya diatur menggunakan metode http. Kami menambahkan pemfilteran pada saat memperbarui entitas, dan pengguna sekarang memiliki kesempatan untuk membangun replikasi dengan sistem mereka.

Pada tahun yang sama, sebuah API muncul untuk menurunkan saldo gudang dan komoditas. Bagian paling berharga dari sistem menjadi tersedia bagi pengguna melalui API - pertukaran dokumen utama dan perkiraan data tentang saldo dan biaya barang.

Pada bulan Desember 2015, RetailCRM menerbitkan perpustakaan pihak ketiga pertama untuk mengakses API kami. Mereka mulai menggunakannya dengan cukup aktif, sementara popularitas layanan secara keseluruhan tumbuh, beban pada API tumbuh lebih cepat daripada beban pada antarmuka web. Sekali, pertumbuhan berubah menjadi lompatan dalam beban.





Dan lompatan ini, yang diperlihatkan oleh panah di sebelah kiri, menyebabkan kekaguman server yang melayani API kami. Selama satu minggu kami memahami apa yang sebenarnya dihasilkan oleh beban ini. Ternyata inilah permintaan yang disiarkan ke API kami dari depan klien. Sekitar 50 pelanggan memakan semuanya. Saat itulah kami menyadari salah satu kesalahan kami - tidak adanya batasan.

Sebagai hasilnya, kami memperkenalkan batasan jumlah permintaan simultan. Dari satu akun menjadi mungkin untuk secara bersamaan membuka tidak lebih dari dua permintaan. Ini cukup untuk bekerja dalam mode replikasi untuk bertukar data dalam mode batch. Dan mereka yang ingin menggunakan kami sebagai backend, sejak saat itu dipaksa untuk lebih mematuhi tarif, karena mereka memperkenalkan pekerjaan pada beberapa akun ke dalam perangkat lunak mereka.

Rapikan

Sejak 2014, permintaan untuk API yang ada telah menjadi bagian penting dari bisnis, dan API itu sendiri menghasilkan jumlah data terbesar dalam pertukaran data dengan pelanggan. Pada 2015, kami meluncurkan proyek untuk membersihkan API. Kami memilih JSON alih-alih XML sebagai format dan mulai membangunnya berdasarkan fitur yang diungkapkan selama implementasi versi sebelumnya:

1. Kemampuan mengelola versi. Versi memungkinkan Anda untuk mengembangkan versi baru tanpa mempengaruhi aplikasi yang ada dan tanpa mengganggu pengguna.
2. Kemampuan bagi pengguna untuk melihat metadata dalam respons yang ia terima.
3. Kemampuan untuk bertukar dokumen besar. Jika kami memproses dokumen dengan jumlah posisi lebih dari 4-5 ribu, ini menjadi masalah bagi server: transaksi panjang, permintaan http panjang. Kami membangun mekanisme khusus yang memungkinkan Anda untuk memperbarui dokumen di bagian-bagian dan mengelola posisi masing-masing dokumen ini dengan mengirimkannya ke server.
4. Alat untuk replikasi - ada di versi sebelumnya.
5. Batas beban seperti warisan rake yang telah diinjak di versi sebelumnya. Batas yang diperkenalkan pada jumlah permintaan dalam periode waktu, jumlah permintaan dan permintaan bersamaan dari satu alamat ip.

Sejak saat itu, kami merilis dua versi minor API dan meluncurkan beberapa API khusus, tetapi secara umum pendekatannya tetap tidak berubah. Format pertukaran yang diperbarui dan arsitektur baru telah memungkinkan untuk memperbaiki kekurangan di API lebih cepat.

API MyStore hari ini

Hari ini API MyStore memecahkan banyak masalah:

• pertukaran data dengan toko online, sistem akuntansi, bank;
• menerima data penyelesaian, laporan;
• gunakan sebagai backend untuk aplikasi klien - aplikasi seluler dan meja kas desktop kami berfungsi melalui API
• mengirim pemberitahuan tentang perubahan data di MyStore - webhooks;
• telepon;
• sistem loyalitas.

Berdasarkan API, CEO kami, Askar Rakhimberdiev, badak dalam waktu empat jam menulis bot telegram yang memuat sisanya melalui API: github.com/arahimberdiev/com-lognex-telegram-moysklad-stock

Sekarang angka kering.

Berikut statistik kami untuk API REST lama:

• 400 perusahaan;
• 600 pengguna;
• 2 juta permintaan per hari;
• 200 Gb / hari lalu lintas keluar.

Dan inilah yang kami sadari dengan semua MyStore API:

• lebih dari 70 integrasi (beberapa di antaranya dapat ditemukan di sini www.moysklad.ru/integratsii );
• 8500 perusahaan;
• 12.000 pengguna;
• 46 juta permintaan per hari;
• 2 Tb / hari untuk lalu lintas keluar.

Apa selanjutnya

Rencana pengembangan API sedang dalam diskusi aktif. Kami mencoba mempertimbangkan pengalaman pengoperasian yang diberikan pengguna kepada kami. Tidak selalu dan tidak semuanya ternyata dilakukan segera, tetapi tidak jauh adalah versi baru dari API dengan metadata yang lebih nyaman dan struktur yang lebih ringan, OAuth untuk otentikasi, API untuk aplikasi yang dibangun ke dalam antarmuka.

Anda dapat mengikuti berita di situs khusus untuk pengembang integrasi dengan MySklad: dev.moysklad.ru .