{"id":34354,"date":"2019-10-31T21:57:51","date_gmt":"2019-10-31T18:57:51","guid":{"rendered":"https:\/\/prohoster.info\/blog\/pisali-api-porvali-xml-dva\/"},"modified":"2019-10-31T21:57:51","modified_gmt":"2019-10-31T18:57:51","slug":"pisali-api-porvali-xml-dva","status":"publish","type":"post","link":"https:\/\/prohoster.info\/it\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"Abbiamo scritto API \u2014 abbiamo stracciato XML (due)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Il primo API di \u041c\u043e\u0435\u0433\u043e\u0421\u043a\u043b\u0430\u0434\u0430 \u00e8 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\u00e0 state sepolte. <\/p>\n

In questo articolo ci sar\u00e0 molto: come \u00e8 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.
\n<\/a><\/noindex>
\nMi chiamo Oleg Alekseev oalexeev<\/a><\/noindex>, sono il direttore tecnico e cofondatore di \u041c\u043e\u0435\u0433\u043e\u0421\u043a\u043b\u0430\u0434\u0430. <\/p>\n

Perch\u00e9 realizzare un API per il servizio<\/h2>\n

\nI 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 \u2014 \u00e8 gi\u00e0 difficile fermarsi. E ormai il quinto, ottavo, decimo servizio rende il lavoro dell'imprenditore pi\u00f9 facile, ma i dati tra questi servizi cloud vengono trasferiti manualmente dagli utenti. Il lavoro diventa un incubo.<\/p>\n

La soluzione ovvia \u00e8 dare agli utenti la possibilit\u00e0 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 \u00e8 un lavoro manuale abbastanza semplice, ma con l'aumento del numero di questi servizi diventa sempre pi\u00f9 difficile.<\/p>\n

Quindi il passo successivo \u00e8 l'API. Con essa, il servizio cloud beneficia del collegamento di pi\u00f9 servizi in un unico punto. L'emergere di un simile ecosistema attira nuovi clienti grazie a opportunit\u00e0 aggiuntive. Un prodotto con una nuova funzionalit\u00e0 diventa pi\u00f9 vantaggioso e utile.<\/p>\n

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.<\/p>\n

Il sistema di contabilit\u00e0 di MoegoSklada si basa su processi semplici. L'aspetto principale \u00e8 la gestione dei documenti primari, la possibilit\u00e0 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\u00e0 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.<\/p>\n

\"Abbiamo
\n<\/p>\n

Primo API di MoegoSklada<\/h2>\n

\nIn dieci anni di attivit\u00e0 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.<\/p>\n

Nel primo anno abbiamo implementato la possibilit\u00e0 di esportare qualsiasi dato in formato XML. All'epoca, per gli utenti era molto pi\u00f9 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. <\/p>\n

In quel periodo abbiamo iniziato a collaborare con Rusagro, che gi\u00e0 utilizzava un ERP 'maturato' per la pianificazione della produzione e della vendita, mentre caricavano i vagoni negli stabilimenti tramite MoegoSklad. Cos\u00ec 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. <\/p>\n

Questa non \u00e8 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. \u00c8 facile generare un tale 'pacco' durante l'esportazione, ma piuttosto complicato da analizzare durante l'importazione, poich\u00e9 in un pacchetto arrivano tutte le informazioni: sia sui nuovi documenti che su quelli gi\u00e0 esistenti.<\/p>\n

Il primo XML API ha avuto vita breve: dopo due anni abbiamo iniziato a ristrutturalo. Gi\u00e0 all'inizio del suo funzionamento abbiamo commesso alcuni errori nella costruzione dell'interfaccia programmativa.<\/p>\n

\"Abbiamo
\nEcco come \u00e8 stato realizzato l'XML API: illustrazione di uno dei nostri architetti. A proposito, aspettatevi i suoi articoli.<\/i><\/p>\n

Ecco i nostri principali errori:<\/p>\n

    \n
  1. La mappatura JAXB \u00e8 stata realizzata direttamente sui bean delle entit\u00e0. Per comunicare con il database utilizziamo Hibernate, e anche su questi bean \u00e8 stata realizzata la mappatura JAXB. Questo errore si \u00e8 presentato quasi subito: qualsiasi aggiornamento della struttura dei dati portava alla necessit\u00e0 di una pronta comunicazione a tutti coloro che utilizzano l'API, oppure alla creazione di workaround che garantissero la compatibilit\u00e0 con la precedente struttura dei dati.<\/li>\n
  2. L'API \u00e8 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\u00e0 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 \u2014 funzionava attraverso una miriade di parametri nella stringa della query. Con uno strumento cos\u00ec 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 \u00e8 diventata una brutta sorpresa, poich\u00e9 fornire un servizio del genere dovrebbe richiedere una diversa tariffazione e, in generale, un'altra comprensione dell'API come prodotto.<\/li>\n
  3. Poich\u00e9 l'API si \u00e8 sviluppata non come prodotto principale, la documentazione riguardante l'API \u00e8 stata prodotta e pubblicata per scarti \u2014 attraverso ingegneria inversa. Questo approccio sembra piuttosto semplice e conveniente, ma contrasta con il lavoro basato su contratti. Questo \u00e8 quando esiste un qualche componente con uno schema di funzionamento predefinito. Lo sviluppatore lo realizza in conformit\u00e0 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\u00e0 necessaria. <\/li>\n
  4. 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'\u00e8 possibilit\u00e0 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\u00f9 la comprensione della sua domanda e della sua funzionalit\u00e0.<\/li>\n<\/ol>\n

    <\/p>\n

    Tentativo numero due: REST API<\/h2>\n

    \nNel 2010 abbiamo cercato di costruire un sistema di scambio con la contabilit\u00e0 online \u2014 BuchSoft. Non ha funzionato. Ma nel processo di integrazione \u00e8 emersa una vera e propria API: un servizio REST di scambio, in cui mancavano libert\u00e0 come le chiamate RPC per le operazioni. Tutta la comunicazione con l'API \u00e8 stata ridotta a uno standard per REST: nella stringa della richiesta si trovava il nome dell'entit\u00e0, 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\u00e0, e gli utenti hanno potuto costruire repliche con i propri sistemi.<\/p>\n

    Nello stesso anno \u00e8 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\u00f9 preziose del sistema: lo scambio di documenti primari e i dati di calcolo sulle giacenze e sul costo dei prodotti.<\/p>\n

    Nel dicembre 2015 RetailCRM ha pubblicato la prima libreria di terze parti per accedere alla nostra API. \u00c8 stata utilizzata piuttosto attivamente, con una crescente popolarit\u00e0 del servizio nel suo insieme, e il carico sull'API cresceva pi\u00f9 velocemente rispetto a quello sull'interfaccia web. A un certo punto, la crescita si \u00e8 trasformata in un salto del carico. <\/p>\n

    \"Abbiamo
    \n
    \n\"Abbiamo
    \n
    \nE 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 \u00e8 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\u00f2. In quel momento, abbiamo compreso uno dei nostri errori: la completa mancanza di limiti. <\/p>\n

    Alla fine abbiamo introdotto un limite al numero di richieste simultanee. Con un singolo account, \u00e8 possibile aprire non pi\u00f9 di due richieste contemporaneamente. Questo \u00e8 sufficiente per lavorare in modalit\u00e0 replica per lo scambio di dati in modalit\u00e0 batch. Coloro che volevano utilizzare il nostro servizio come backend, da questo momento in poi, sono stati costretti a rispettare di pi\u00f9 le tariffe, poich\u00e9 hanno integrato nei loro strumenti software il lavoro con pi\u00f9 account.<\/p>\n

    Mettiamo in ordine<\/h2>\n

    \nGi\u00e0 dal 2014, la domanda per l'API esistente \u00e8 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\u00e0 emerse nell'implementazione della versione precedente:<\/p>\n

      \n
    1. Possibilit\u00e0 di gestire le versioni. La versioning consente di sviluppare una nuova versione senza influenzare l'applicazione esistente e senza interrompere il lavoro degli utenti. <\/li>\n
    2. Possibilit\u00e0 per l'utente di vedere i metadata nella risposta stessa che riceve.<\/li>\n
    3. Possibilit\u00e0 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.<\/li>\n
    4. Strumenti per la replica - c'erano anche nella versione precedente.<\/li>\n
    5. Limiti di carico - come eredit\u00e0 delle difficolt\u00e0 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.<\/li>\n<\/ol>\n

      \nDa quel momento abbiamo rilasciato due versioni minori dell'API e abbiamo avviato diversi API specializzati, ma nel complesso l'approccio \u00e8 rimasto invariato. Il formato di scambio aggiornato e la nuova architettura hanno permesso di risolvere i difetti dell'API molto pi\u00f9 rapidamente.<\/p>\n

      API del Mio Magazzino oggi<\/h2>\n

      \nOggi l'API del Mio Magazzino risolve molteplici compiti:<\/p>\n