La prima API MySklad è apparsa 10 anni fa. Per tutto questo tempo abbiamo lavorato sulle versioni esistenti dell'API e ne abbiamo sviluppato di nuove. E diverse versioni dell’API sono già state sepolte.
Questo articolo conterrà molte cose: come è stata creata l'API, perché il servizio cloud ne ha bisogno, cosa offre agli utenti, quali errori siamo riusciti a commettere e cosa vogliamo fare dopo.
Il mio nome è Oleg Alekseev , sono il direttore tecnico e co-fondatore di MySklad.
Perché creare un'API per un servizio
I nostri clienti, che sono decine di migliaia di imprenditori, utilizzano attivamente soluzioni cloud: servizi bancari, negozi online, contabilità delle materie prime, CRM. Una volta che ti connetti a uno, è difficile fermarsi. E ora il quinto, l'ottavo, il decimo servizio semplificano il lavoro dell'imprenditore, ma gli utenti trasferiscono manualmente i dati tra questi servizi cloud. Il lavoro si trasforma in un incubo.
La soluzione ovvia è offrire agli utenti la possibilità di trasferire dati tra servizi cloud. Ad esempio, importa ed esporta dati come file, che possono poi essere caricati sul servizio desiderato. I file vengono solitamente modificati per adattarsi al formato di ciascun servizio. Si tratta di lavori manuali più o meno semplici, ma con l'aumento del numero di questi servizi, diventa sempre più difficile da eseguire.
Pertanto, il passaggio successivo è l'API. In questo modo il servizio cloud beneficia del fatto che collega più servizi in un unico punto. L'emergere di un tale ecosistema attira nuovi clienti grazie a ulteriori opportunità. Un prodotto con nuove funzionalità diventa più redditizio e utile.
Se crei le tue interfacce di programmazione, questo attira venditori di terze parti sotto forma di programmatori che conoscono il tuo prodotto grazie all'API. Cominciano a creare soluzioni basate sull'API proposta e guadagnano automatizzando le attività dei loro clienti.
Il sistema contabile MySklad si basa su processi semplici. L'importante è lavorare con documenti primari, poter accettare e spedire merci e ricevere rapporti commerciali basati su documenti primari. C'è anche il trasferimento dei dati, ad esempio alla contabilità cloud, e la loro ricezione dai sistemi bancari o dai punti vendita. Lavoriamo anche con negozi online: riceviamo informazioni sui prodotti e inviamo informazioni sui saldi.
La prima API di MySklad
Nel corso dei 10 anni di lavoro di MySklad con API, abbiamo acquisito tutti i tipi di integrazioni che ci consentono di scambiare dati, lavorare con le banche, effettuare pagamenti e utilizzare la telefonia esterna.
Nel primo anno abbiamo reso possibile il download di tutti i dati in formato XML. Allora era molto più chiaro e comune per gli utenti mantenere i dati offline, piuttosto che in qualche cloud, e noi glieli abbiamo forniti. Il caricamento è stato avviato mediante esportazione manuale dall'interfaccia. Cioè, non poteva ancora essere chiamata API.
Allo stesso tempo, abbiamo iniziato a collaborare con l'azienda Rusagro: utilizzavano già un ERP “adulto” per la pianificazione della produzione e delle vendite, ma automatizzavano il caricamento delle auto negli stabilimenti di MySklad. Abbiamo ottenuto così i primi rudimenti di una vera e propria API: lo scambio tra il nostro servizio e l'ERP avveniva inviando un file di grandi dimensioni con dati su tutti i tipi di documenti.
Questa è una buona opzione per lo scambio di dati batch, ma insieme ai documenti abbiamo dovuto trasferire le loro dipendenze: informazioni su merci, appaltatori e magazzini. Un tale dump non è così difficile da generare durante l'esportazione, ma è piuttosto difficile da analizzare durante l'importazione, poiché tutte le informazioni sono contenute in un unico pacchetto: sia sui nuovi documenti che su quelli esistenti.
La prima API XML non durò a lungo: due anni dopo abbiamo iniziato a ricostruirla. Già all'inizio del suo lavoro abbiamo commesso diversi errori durante la creazione dell'interfaccia del software.
Come è stata realizzata l'API XML: illustrazione di uno dei nostri architetti. A proposito, rimanete sintonizzati per i suoi articoli.
Ecco i nostri principali errori:
- La markup JAXB è stata eseguita direttamente sui bean entità. Usiamo Hibernate per comunicare con il database e il markup JAXB è stato creato per gli stessi bean. Questo errore è apparso quasi immediatamente: qualsiasi aggiornamento della struttura dati ha comportato la necessità di avvisare urgentemente tutti coloro che utilizzano l'API o di costruire stampelle che garantissero la compatibilità con la struttura dati precedente.
- L'API è cresciuta come componente aggiuntivo e inizialmente non abbiamo definito quale parte del prodotto fosse. Non pensavano nemmeno se l’API fosse qualcosa di importante, se fosse necessario mantenere la compatibilità con le versioni precedenti per i suoi primi clienti. Ad un certo punto, il numero di utenti API era circa il 5% del numero limitato e non veniva prestata loro alcuna attenzione. Il filtraggio universale effettuato un tempo ci ha portato a essere utilizzati come backend. Questo filtraggio non era affatto GraphQL, ma qualcosa del genere: funzionava attraverso molti parametri della stringa di query. Con uno strumento così potente per gli utenti era difficile resistere e le richieste venivano trasferite a noi in modo che arrivassero direttamente dall'interfaccia utente dei loro negozi online. La situazione è stata una spiacevole sorpresa, perché la fornitura di un tale servizio dovrebbe richiedere prezzi diversi e una comprensione generalmente diversa dell'API stessa come prodotto.
- Dato che l'API non è stata sviluppata come prodotto principale, la documentazione API è stata prodotta e pubblicata in via residuale, tramite reverse engineering. Questo percorso sembra abbastanza semplice e conveniente, ma contraddice il lavoro con contratto. Questo è quando è presente un determinato componente con uno schema operativo preimpostato. Lo sviluppatore lo implementa secondo questo schema e compito, il componente viene testato e il cliente riceve un prodotto che corrisponde all'idea dell'analista. Il reverse engineering lancia sul mercato un prodotto che semplicemente esiste: con stampelle, soluzioni strane e biciclette al posto della funzionalità necessaria.
- L'intero flusso di richieste che arrivava attraverso l'API poteva essere analizzato come nient'altro che un registro di Nginx o del server delle applicazioni. Questo non ci ha permesso di individuare aree tematiche, se non forse da parte degli utenti e degli abbonati. Se non c'è modo di regolamentare la richiesta o la registrazione del cliente, diventa impossibile analizzare la situazione. Questo problema ha avuto il minimo impatto sullo sviluppo dell'API; si tratta più di comprenderne la rilevanza e la funzionalità.
Tentativo numero due: API REST
Nel 2010 abbiamo provato a costruire un sistema di scambio con contabilità online: BukhSoft. Non è decollato. Ma durante il processo di integrazione è apparsa un'API a tutti gli effetti: un servizio di scambio REST, dove non c'erano libertà come l'accesso alle operazioni sotto forma di chiamate RPC. Tutta la comunicazione con l'API è stata portata in modalità standard per il riposo: la riga di query contiene il nome dell'entità e l'operazione eseguita con essa viene specificata utilizzando il metodo http. Abbiamo aggiunto filtri in base a quando le entità sono state aggiornate e gli utenti ora hanno l'opportunità di creare repliche con i propri sistemi.
Nello stesso anno è apparsa un'API per lo scarico dei saldi di magazzino e di inventario. Le parti più preziose del sistema sono diventate disponibili agli utenti tramite API: lo scambio di documenti primari e dati calcolati sui saldi e sul costo delle merci.
Nel dicembre 2015, RetailCRM ha pubblicato la prima libreria di terze parti per accedere alla nostra API. Cominciò ad essere utilizzato abbastanza attivamente, mentre la popolarità del servizio nel suo insieme cresceva, il carico sull'API cresceva più velocemente del carico sull'interfaccia web. Un giorno la crescita si trasformò in un aumento del carico.
E questo salto, indicato dalla freccia a sinistra, ha completamente stupito il server che serve la nostra API. Abbiamo passato una settimana a capire cosa stesse esattamente generando questo carico. Si è scoperto che queste sono le stesse richieste trasmesse alla nostra API dal fronte dei clienti. Circa 50 clienti hanno mangiato tutto. È stato allora che ci siamo resi conto di uno dei nostri errori: la completa mancanza di limiti.
Di conseguenza, abbiamo introdotto un limite al numero di richieste simultanee. Ora è possibile aprire non più di due richieste contemporaneamente da un conto. Questo è sufficiente per lavorare in modalità replica per lo scambio di dati in modalità batch. E chi ha voluto usarci come backend, da quel momento in poi, è stato costretto a rispettare meglio le tariffe, poiché ha introdotto nel proprio software il lavoro su più account.
Mettiamolo in ordine
Già dal 2014 la richiesta dell’API esistente è diventata una parte importante del business e l’API stessa genera il maggior volume di dati nello scambio di dati con i clienti. Nel 2015 abbiamo lanciato un progetto per ripulire l'API. Abbiamo scelto JSON invece di XML come formato e abbiamo iniziato a costruirlo in base alle funzionalità identificate durante l'implementazione della versione precedente:
- Possibilità di gestire le versioni. Il controllo delle versioni consente di sviluppare una nuova versione senza influire sull'applicazione esistente o interrompere l'esperienza dell'utente.
- La possibilità per l'utente di vedere i metadati nella risposta stessa che riceve.
- Possibilità di scambiare documenti di grandi dimensioni. Se elaboriamo un documento con più di 4-5mila posizioni, questo diventa un problema per il server: una transazione lunga, una richiesta http lunga. Abbiamo creato un meccanismo speciale che ti consente di aggiornare un documento in parti e gestire le singole posizioni di questo documento inviandole al server.
- Gli strumenti per la replica erano presenti anche nella versione precedente.
- I limiti di carico sono come un'eredità del rastrello calpestato nella versione precedente. Abbiamo introdotto limiti al numero di richieste in un periodo di tempo, al numero di richieste parallele e alle richieste da un indirizzo IP.
Da allora, abbiamo rilasciato due versioni minori dell'API e lanciato diverse API specializzate, ma l'approccio generale è rimasto invariato. Il formato di scambio aggiornato e la nuova architettura hanno permesso di correggere i difetti nell'API molto più velocemente.
API MySklad oggi
Oggi l'API MySklad risolve molti problemi:
- scambio dati con negozi online, sistemi contabili, banche;
- ottenere dati e report calcolati;
- utilizzare come backend per le applicazioni client: le nostre applicazioni mobili e il registratore di cassa desktop funzionano tramite API
- invio di notifiche sulle modifiche dei dati in MySklad - webhook;
- telefonia;
- sistemi di fidelizzazione.
Sulla base dell'API, il nostro CEO Askar Rakhimberdiev in quattro ore ho scritto un bot di Telegram che estrae gli avanzi attraverso l'API:
Adesso numeri secchi.
Ecco le nostre statistiche per la vecchia API REST:
- 400 aziende;
- 600 utenti;
- 2 milioni di richieste al giorno;
- 200 GB/giorno di traffico in uscita.
Ed ecco cosa abbiamo pensato per tutte le API MySklad:
- più di 70 integrazioni (alcune di esse possono essere visualizzate qui );
- 8500 aziende;
- 12 utenti;
- 46 milioni di richieste al giorno;
- 2 TB/giorno di traffico in uscita.
Cosa c'è Next
I piani di sviluppo dell'API sono oggetto di discussione attiva. Cerchiamo di tenere conto dell'esperienza operativa che gli utenti ci forniscono. Non è sempre possibile fare tutto in una volta, ma una nuova versione dell'API è proprio dietro l'angolo con metadati più convenienti e una struttura meno soffice, OAuth per l'autenticazione e un'API per le applicazioni integrate nell'interfaccia.
Puoi seguire le notizie su un sito web speciale per gli sviluppatori di integrazioni con MySklad: .
Fonte: habr.com