Il primo API di МоегоСклада è apparso 10 anni fa. In tutto questo tempo abbiamo lavorato sulle versioni esistenti dell'API e ne abbiamo sviluppate di nuove. E parecchie versioni dell'API sono già state sepolte.
In questo articolo ci sarà molto: come è stato creato l'API, a cosa serve a un servizio cloud, cosa offre agli utenti, quali errori abbiamo commesso e cosa vogliamo fare in futuro.
Mi chiamo Oleg Alekseev , sono il direttore tecnico e cofondatore di МоегоСклада.
Perché realizzare un API per il servizio
I nostri clienti, che sono decine di migliaia di imprenditori, utilizzano attivamente soluzioni cloud: banking, negozi online, gestione delle merci, CRM. Se ci si connette a uno — è già difficile fermarsi. E ormai il quinto, ottavo, decimo servizio rende il lavoro dell'imprenditore più facile, ma i dati tra questi servizi cloud vengono trasferiti manualmente dagli utenti. Il lavoro diventa un incubo.
La soluzione ovvia è dare agli utenti la possibilità di trasferire dati tra servizi cloud. Ad esempio, importare ed esportare dati come file, che possono poi essere caricati nel servizio desiderato. I file di solito vengono adattati al formato di ogni servizio. Questo è un lavoro manuale abbastanza semplice, ma con l'aumento del numero di questi servizi diventa sempre più difficile.
Quindi il passo successivo è l'API. Con essa, il servizio cloud beneficia del collegamento di più servizi in un unico punto. L'emergere di un simile ecosistema attira nuovi clienti grazie a opportunità aggiuntive. Un prodotto con una nuova funzionalità diventa più vantaggioso e utile.
Se si creano interfacce di programmazione proprie, questo attira venditori esterni sotto forma di programmatori che conoscono il tuo prodotto grazie all'API. Iniziano a costruire soluzioni basate sull'API fornito e guadagnano denaro automatizzando i compiti dei propri clienti.
Il sistema di contabilità di MoegoSklada si basa su processi semplici. L'aspetto principale è la gestione dei documenti primari, la possibilità di effettuare ricezioni e spedizioni di merci, e di generare report aziendali sulla base dei documenti primari. Inoltre, ci sono trasferimenti di dati, ad esempio verso contabilità cloud, e l'acquisizione di dati da sistemi bancari o punti vendita. Collaboriamo anche con negozi online: riceviamo informazioni sui prodotti e inviamo dati sulle giacenze.
Primo API di MoegoSklada
In dieci anni di attività di MoegoSklada con API, abbiamo sviluppato varie integrazioni che consentono lo scambio di dati, lavorare con le banche, effettuare pagamenti e utilizzare la telefonia esterna.
Nel primo anno abbiamo implementato la possibilità di esportare qualsiasi dato in formato XML. All'epoca, per gli utenti era molto più chiaro e consueto mantenere i dati offline piuttosto che in qualche cloud, e noi glielo abbiamo fornito. L'esportazione veniva avviata tramite un'esportazione manuale dall'interfaccia. Quindi, non si poteva ancora definire un'API.
In quel periodo abbiamo iniziato a collaborare con Rusagro, che già utilizzava un ERP 'maturato' per la pianificazione della produzione e della vendita, mentre caricavano i vagoni negli stabilimenti tramite MoegoSklad. Così abbiamo avuto i primi embrioni di una vera API: lo scambio tra il nostro servizio e l'ERP avveniva tramite l'invio di un grande file di dati su tutti i tipi di documenti.
Questa non è una cattiva opzione per lo scambio di dati in batch, ma insieme ai documenti si dovevano trasmettere anche le loro dipendenze: informazioni sui prodotti, sui partner commerciali e sui magazzini. È facile generare un tale 'pacco' durante l'esportazione, ma piuttosto complicato da analizzare durante l'importazione, poiché in un pacchetto arrivano tutte le informazioni: sia sui nuovi documenti che su quelli già esistenti.
Il primo XML API ha avuto vita breve: dopo due anni abbiamo iniziato a ristrutturalo. Già all'inizio del suo funzionamento abbiamo commesso alcuni errori nella costruzione dell'interfaccia programmativa.
Ecco come è stato realizzato l'XML API: illustrazione di uno dei nostri architetti. A proposito, aspettatevi i suoi articoli.
Ecco i nostri principali errori:
- La mappatura JAXB è stata realizzata direttamente sui bean delle entità. Per comunicare con il database utilizziamo Hibernate, e anche su questi bean è stata realizzata la mappatura JAXB. Questo errore si è presentato quasi subito: qualsiasi aggiornamento della struttura dei dati portava alla necessità di una pronta comunicazione a tutti coloro che utilizzano l'API, oppure alla creazione di workaround che garantissero la compatibilità con la precedente struttura dei dati.
- L'API è nata come una sorta di complemento, e inizialmente non abbiamo definito quale parte del prodotto costituisse. Non ci siamo nemmeno interrogati se l'API fosse qualcosa di importante, se fosse necessario mantenere la retrocompatibilità per i suoi primi clienti. In un certo momento, il numero degli utenti dell'API costituiva circa il 5% del numero totale piuttosto limitato, e non si prestava loro attenzione. La filtrazione universale realizzata in quel momento ha portato alla situazione in cui siamo stati utilizzati come backend. Questa filtrazione non era affatto GraphQL, ma qualcosa di simile — funzionava attraverso una miriade di parametri nella stringa della query. Con uno strumento così potente, gli utenti trovavano difficile astenersi, e le richieste venivano direzionate a noi in modo tale che venissero inviate direttamente dall'interfaccia utente dei loro negozi online. La situazione è diventata una brutta sorpresa, poiché fornire un servizio del genere dovrebbe richiedere una diversa tariffazione e, in generale, un'altra comprensione dell'API come prodotto.
- Poiché l'API si è sviluppata non come prodotto principale, la documentazione riguardante l'API è stata prodotta e pubblicata per scarti — attraverso ingegneria inversa. Questo approccio sembra piuttosto semplice e conveniente, ma contrasta con il lavoro basato su contratti. Questo è quando esiste un qualche componente con uno schema di funzionamento predefinito. Lo sviluppatore lo realizza in conformità a questo schema e obiettivo, il componente viene testato, e il cliente riceve un prodotto che corrisponde all'idea dell'analista. L'ingegneria inversa, invece, immette sul mercato un prodotto che semplicemente esiste: con workaround, soluzioni stravaganti e biciclette al posto della funzionalità necessaria.
- Tutto il flusso di richieste che arrivava tramite l'API poteva essere analizzato al massimo come i log di Nginx o del server applicativo. Questo non permetteva di isolare le aree tematiche, a meno che non si suddividesse per utenti e abbonati. Se non c'è possibilità di regolare la registrazione dell'app o dei clienti, analizzare la situazione diventa impossibile. Questo problema ha avuto il minore impatto sullo sviluppo dell'API, riguarda più la comprensione della sua domanda e della sua funzionalità.
Tentativo numero due: REST API
Nel 2010 abbiamo cercato di costruire un sistema di scambio con la contabilità online — BuchSoft. Non ha funzionato. Ma nel processo di integrazione è emersa una vera e propria API: un servizio REST di scambio, in cui mancavano libertà come le chiamate RPC per le operazioni. Tutta la comunicazione con l'API è stata ridotta a uno standard per REST: nella stringa della richiesta si trovava il nome dell'entità, mentre l'operazione da eseguire su di essa veniva specificata tramite il metodo http. Abbiamo aggiunto la filtrazione in base al momento di aggiornamento delle entità, e gli utenti hanno potuto costruire repliche con i propri sistemi.
Nello stesso anno è stata introdotta l'API per l'estrazione delle giacenze di magazzino e dei prodotti. Attraverso l'API, sono diventate disponibili per gli utenti le parti più preziose del sistema: lo scambio di documenti primari e i dati di calcolo sulle giacenze e sul costo dei prodotti.
Nel dicembre 2015 RetailCRM ha pubblicato la prima libreria di terze parti per accedere alla nostra API. È stata utilizzata piuttosto attivamente, con una crescente popolarità del servizio nel suo insieme, e il carico sull'API cresceva più velocemente rispetto a quello sull'interfaccia web. A un certo punto, la crescita si è trasformata in un salto del carico.
E quel salto, indicato dalla freccia a sinistra, ha completamente stupito il server che gestiva la nostra API. Abbiamo passato una settimana a capire cosa generasse esattamente quel carico. Si è scoperto che si trattava proprio di quelle richieste trasmesse alla nostra API dai front-end dei clienti. Sono state circa 50 i clienti a generare tutto ciò. In quel momento, abbiamo compreso uno dei nostri errori: la completa mancanza di limiti.
Alla fine abbiamo introdotto un limite al numero di richieste simultanee. Con un singolo account, è possibile aprire non più di due richieste contemporaneamente. Questo è sufficiente per lavorare in modalità replica per lo scambio di dati in modalità batch. Coloro che volevano utilizzare il nostro servizio come backend, da questo momento in poi, sono stati costretti a rispettare di più le tariffe, poiché hanno integrato nei loro strumenti software il lavoro con più account.
Mettiamo in ordine
Già dal 2014, la domanda per l'API esistente è diventata una parte importante del business, e l'API stessa generava il maggiore volume di dati nello scambio di informazioni con i clienti. Nel 2015 abbiamo lanciato un progetto per mettere in ordine l'API. Abbiamo scelto il formato JSON invece di XML e abbiamo iniziato a costruirlo sulla base delle peculiarità emerse nell'implementazione della versione precedente:
- Possibilità di gestire le versioni. La versioning consente di sviluppare una nuova versione senza influenzare l'applicazione esistente e senza interrompere il lavoro degli utenti.
- Possibilità per l'utente di vedere i metadata nella risposta stessa che riceve.
- Possibilità di scambiare grandi documenti. Se trattiamo un documento con un numero di articoli maggiore di 4-5 mila, questo diventa un problema per il server: transazione lunga, richiesta http lunga. Abbiamo costruito un meccanismo speciale che consente di aggiornare il documento a pezzi e gestire singoli articoli di quel documento, inviandoli al server.
- Strumenti per la replica - c'erano anche nella versione precedente.
- Limiti di carico - come eredità delle difficoltà riscontrate nella versione precedente. Abbiamo introdotto limiti al numero di richieste in un intervallo di tempo, al numero di richieste parallele e alle richieste da un singolo indirizzo ip.
Da quel momento abbiamo rilasciato due versioni minori dell'API e abbiamo avviato diversi API specializzati, ma nel complesso l'approccio è rimasto invariato. Il formato di scambio aggiornato e la nuova architettura hanno permesso di risolvere i difetti dell'API molto più rapidamente.
API del Mio Magazzino oggi
Oggi l'API del Mio Magazzino risolve molteplici compiti:
- scambio di dati con negozi online, sistemi contabili, banche;
- ottenimento di dati di calcolo, report;
- utilizzo come backend per applicazioni client - le nostre applicazioni mobili e il punto cassa desktop funzionano tramite API.
- invio di notifiche sulle modifiche dei dati in MieiMagazzini — webhooks;
- telefonia;
- sistemi di fidelizzazione.
Basato su API, il nostro amministratore delegato Askar Rakhimberdiev in quattro ore ha scritto un bot Telegram che recupera tramite API i rimanenti:
Ora solo numeri freddi.
Ecco le nostre statistiche sul vecchio REST API:
- 400 aziende;
- 600 utenti;
- 2 milioni di richieste al giorno;
- 200 GB/giorno di traffico in uscita.
Ecco dove siamo arrivati con tutte le API di MieiMagazzini:
- oltre 70 integrazioni (alcune delle quali possono essere visualizzate qui );
- 8500 aziende;
- 12.000 utenti;
- 46 milioni di richieste al giorno;
- 2 TB/giorno di traffico in uscita.
E ora?
I piani per lo sviluppo dell'API sono attualmente in attiva discussione. Cerchiamo di tenere conto dell'esperienza d'uso fornita dagli utenti. Non sempre e non tutto può essere fatto subito, ma la nuova versione dell'API con metadati più comodi e una struttura meno complessa, OAuth per l'autenticazione e API per app integrate nell'interfaccia è dietro l'angolo.
Per seguire le notizie, è possibile visitare il sito dedicato per gli sviluppatori di integrazioni con MieiMagazzini: .
Fonte: habr.com
