{"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\/nl\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"We schreven API \u2014 we doorbraken XML (twee)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

De eerste API van MijnVoorraad verscheen 10 jaar geleden. Gedurende deze tijd hebben we gewerkt aan de bestaande versies van de API en ontwikkelen we nieuwe. Al enkele versies van de API zijn inmiddels begraven. <\/p>\n

In dit artikel komt er veel voorbij: hoe we de API hebben gemaakt, waarom deze nodig is voor de cloudservice, wat gebruikers ervan hebben, op welke hobbels we zijn gestuit en wat we verder willen doen.
\n<\/a><\/noindex>
\nMijn naam is Oleg Alekseev oalexeev<\/a><\/noindex>, ik ben technisch directeur en medeoprichter van MijnVoorraad. <\/p>\n

Waarom een API maken voor de service<\/h2>\n

\nOnze klanten, wat tientallen duizenden ondernemers zijn, maken actief gebruik van cloudoplossingen: bankieren, webwinkels, voorraadbeheer, CRM. Eenmaal aangesloten op \u00e9\u00e9n service is het al moeilijk om te stoppen. En dan is er al de vijfde, achtste, tiende service die het werk van de ondernemer vergemakkelijkt, maar gebruikers verplaatsen de gegevens tussen deze cloudservices handmatig. Het werk verandert in een nachtmerrie.<\/p>\n

De voor de hand liggende oplossing is om gebruikers de mogelijkheid te geven om gegevens tussen cloudservices uit te wisselen. Bijvoorbeeld, gegevens importeren en exporteren als bestanden die vervolgens in de gewenste service kunnen worden ge\u00fcpload. De bestanden worden meestal aangepast aan het formaat van elke service. Dit is meer of minder eenvoudig handwerk, maar naarmate het aantal van deze services toeneemt, wordt het steeds moeilijker om dit uit te voeren.<\/p>\n

Daarom is de volgende stap de API. Hiermee wint de cloudservice door meerdere services op \u00e9\u00e9n plek te verbinden. De komst van zo'n ecosysteem trekt nieuwe klanten aan door extra mogelijkheden. Een product met nieuwe functionaliteiten wordt voordeliger en nuttiger.<\/p>\n

Als je eigen programmatic interfaces cre\u00ebert, trekt dat externe verkopers aan in de vorm van programmeurs die over jouw product leren dankzij de API. Zij beginnen oplossingen te bouwen op basis van de aangeboden API en verdienen geld met het automatiseren van de taken van hun klanten.<\/p>\n

Het boekhoudsysteem van MijnVoorraad is gebaseerd op eenvoudige processen. Het belangrijkste is het werken met primaire documenten, de mogelijkheid om goederen te ontvangen en af te leveren, en op basis van de basisdocumenten rapporten voor het bedrijfsleven te verkrijgen. Ook is er de overdracht van gegevens, bijvoorbeeld naar cloudboekhouding, en het verkrijgen ervan uit banksystemen of retailpunten. Daarnaast werken we samen met webwinkels: we ontvangen informatie over producten en sturen gegevens over voorraadniveaus.<\/p>\n

\"We
\n<\/p>\n

De eerste API van MijnMagazin<\/h2>\n

\nIn de 10 jaar dat MijnMagazin met API werkt, hebben we verschillende integraties ontwikkeld die het mogelijk maken om gegevens uit te wisselen, met banken te werken, betalingen uit te voeren en externe telefonie te gebruiken.<\/p>\n

In het eerste jaar hebben we de mogelijkheid gemaakt om gegevens in XML-indeling te exporteren. Toen was het voor gebruikers veel duidelijker en gebruikelijker om gegevens offline te bewaren, in plaats van in een of andere cloud, en dat hebben we hen gegeven. De export werd handmatig gestart vanuit de interface. Dus zo kon je het nog niet echt een API noemen. <\/p>\n

Toen zijn we gaan samenwerken met het bedrijf Rusagro \u2014 zij gebruikten al een 'volwassen' ERP-systeem voor productieplanning en verkoop, maar de belading van wagons bij de fabrieken werd geautomatiseerd in MijnMagazin. Zo kregen we de eerste aanzetten van een echte API: de uitwisseling tussen onze service en ERP vond plaats door het verzenden van een groot bestand met gegevens over alle documenten. <\/p>\n

Dit was een goede optie voor batchgegevensuitwisseling, maar samen met documenten moesten ook de afhankelijkheden worden doorgegeven: informatie over producten, partners en magazijnen. Zo'n rommel is niet moeilijk te genereren bij export, maar behoorlijk moeilijk te verwerken bij import, aangezien in \u00e9\u00e9n pakket alle gegevens binnenkomen: zowel over nieuwe documenten, als over al bestaande.<\/p>\n

De eerste XML API heeft niet lang bestaan \u2014 na twee jaar zijn we begonnen met de herstructurering ervan. Al aan het begin van de werking hebben we een aantal fouten gemaakt bij het bouwen van de programmeerinterface.<\/p>\n

\"We
\nHoe de XML API werd gemaakt: een illustratie van een van onze architecten. Overigens, verwacht ook zijn artikelen.<\/i><\/p>\n

Dit zijn onze belangrijkste fouten:<\/p>\n

    \n
  1. De JAXB-markering was direct op de entity beans gedaan. Voor communicatie met de database gebruiken we Hibernate, en op deze binen is de JAXB-markering gedaan. Deze fout kwam bijna onmiddellijk aan het licht: elke wijziging in de datastructuur leidde tot de noodzaak om urgent alle gebruikers van de API te informeren, of het bouwen van noodoplossingen die compatibiliteit met de vorige datastructuur waarborgden.<\/li>\n
  2. De API ontwikkelde zich als een aanvulling en aanvankelijk bepaalden we niet welk deel van het product het vormde. We dachten ook niet na over de vraag of de API iets belangrijks was en of we terugwaartse compatibiliteit voor de eerste klanten moesten ondersteunen. Een tijdje maakte ongeveer 5% van het totale, kleine aantal gebruikers gebruik van de API, en we gaven er weinig aandacht aan. De eerder ge\u00efmplementeerde universele filtering leidde ertoe dat we als backend werden gebruikt. Deze filtering was helemaal geen GraphQL, maar iets dat daarop leek \u2014 het werkte met tal van parameters in de querystring. Met zo'n krachtig instrument was het voor gebruikers moeilijk om zich te onthouden, en aanvragen werden direct via de UI van hun webshops naar ons verzonden. De situatie werd een onaangename verrassing, omdat het aanbieden van zo'n dienst een andere prijsstelling en een heel andere benadering van de API als product zou moeten vereisen.<\/li>\n
  3. Omdat de API zich niet als een hoofdproduct ontwikkelde, werd de documentatie voor de API op een restbasis gemaakt en gepubliceerd \u2014 via reverse engineering. Deze aanpak lijkt vrij eenvoudig en handig, maar is in strijd met de contractuele vereisten. Dit is wanneer er een component is met een vooraf vastgestelde werkstructuur. De ontwikkelaar implementeert deze structuur en taak, de component wordt getest, en de klant ontvangt een product dat overeenkomt met de visie van de analist. Reverse engineering daarentegen gooit een product op de markt dat er gewoon is: met tijdelijke oplossingen, vreemde beslissingen en fietsen in plaats van de benodigde functionaliteit. <\/li>\n
  4. De volledige stroom aanvragen die via de API binnenkwamen, kon niet verder worden geanalyseerd dan de log van de Nginx of de applicatieserver. Dit maakte het onmogelijk om onderwerpen te onderscheiden, behalve om deze op gebruikers en abonnees te splitsen. Als er geen mogelijkheid is om de registratie van applicaties of cli\u00ebnten te regelen, wordt het onmogelijk om de situatie te analyseren. Dit probleem heeft in de minste mate invloed gehad op de ontwikkeling van de API; het gaat meer om het begrijpen van de vraag ernaar en de functionaliteit die deze biedt.<\/li>\n<\/ol>\n

    <\/p>\n

    Poging nummer twee: REST API<\/h2>\n

    \nIn 2010, we attempted to build a system for exchanging data with an online accounting service \u2014 BukhSoft. It didn\u2019t take off. However, during the integration process, we developed a full-featured API: a REST exchange service, devoid of liberties like RPC calls for operations. All communication with the API was standardized to the REST mode: the request string contains the name of the entity, while the operation performed on it is defined by the HTTP method. We added filtering based on the moment of updating entities, giving users the ability to build replication with their systems.<\/p>\n

    That same year, we introduced an API for exporting warehouse and product balances. Through the API, the most valuable parts of the system became accessible to users \u2014 the exchange of primary documents and the calculation data for balances and product costs.<\/p>\n

    In December 2015, RetailCRM published the first third-party library for accessing our API. It became quite popular, leading to an increase in the popularity of the service overall, with the load on the API growing faster than that on the web interface. At one point, growth turned into a spike in load. <\/p>\n

    \"We
    \n
    \n\"We
    \n
    \nAnd this spike, indicated by the arrow on the left, completely astonished the server servicing our API. We spent a week figuring out what exactly was generating this load. It turned out to be those very requests being relayed to our API from clients' fronts. About 50 clients accounted for the entire load. At that moment, we realized one of our mistakes \u2014 the total lack of limits. <\/p>\n

    As a result, we implemented a limit on the number of simultaneous requests. From one account, it became possible to open no more than two requests at the same time. This is sufficient for operating in replication mode for data exchange in batch mode. Those who wanted to use us as a backend had to comply more with the tariffs, as they had to implement work with multiple accounts in their software.<\/p>\n

    We are organizing<\/h2>\n

    \nSince 2014, the demand for the existing API became an important part of the business, and the API itself generated the largest volume of data in data exchanges with clients. In 2015, we launched a project to bring the API in order. We chose JSON as the format instead of XML and began to build it based on the features that emerged during the implementation of the previous version:<\/p>\n

      \n
    1. Mogelijkheid om versies te beheren. Versiebeheer stelt ons in staat om een nieuwe versie te ontwikkelen zonder de bestaande applicatie te be\u00efnvloeden en de werking voor gebruikers te verstoren. <\/li>\n
    2. Mogelijkheid voor gebruikers om metadata in het antwoord te zien dat zij ontvangen.<\/li>\n
    3. Mogelijkheid om grote documenten uit te wisselen. Wanneer we een document met meer dan 4-5 duizend items verwerken, wordt het een probleem voor de server: lange transactie, lange http-aanroep. We hebben een speciaal mechanisme ontwikkeld om documenten in delen bij te werken en afzonderlijke items van dat document te beheren door ze naar de server te sturen.<\/li>\n
    4. Tools voor replicatie \u2014 waren er ook in de vorige versie.<\/li>\n
    5. Belastinglimieten \u2014 als gevolg van fouten die zijn gemaakt in de vorige versie. We hebben limieten ingesteld voor het aantal verzoeken in een bepaalde tijd, het aantal gelijktijdige verzoeken en verzoeken vanuit \u00e9\u00e9n ip-adres.<\/li>\n<\/ol>\n

      \nSindsdien hebben we twee minor API-versies uitgebracht en verschillende gespecialiseerde API's gelanceerd, maar de aanpak is grotendeels hetzelfde gebleven. Het vernieuwde uitwisselingsformaat en de nieuwe architectuur hebben het mogelijk gemaakt om tekortkomingen in de API veel sneller te verhelpen.<\/p>\n

      API van MijnVoorraad vandaag<\/h2>\n

      \nVandaag de dag lost de API van MijnVoorraad veel taken op:<\/p>\n