{"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\/hu\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"API-t \u00edrtunk \u2014 sz\u00e9tt\u00e9pt\u00fck az XML-t (kett\u0151)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

A MyWarehouse API appeared 10 years ago. All this time we have been working on existing versions of the API and developing new ones. And several versions of the API have already been retired. <\/p>\n

This article will cover a lot of topics: how the API was created, why it is needed for cloud services, what it offers to users, what pitfalls we encountered, and what we want to do next.
\n<\/a><\/noindex>
\nMy name is Oleg Alexeev oalexeev<\/a><\/noindex>, I am the technical director and co-founder of MyWarehouse. <\/p>\n

Why create an API for a service<\/h2>\n

\nOur clients, which number in the tens of thousands, actively use cloud solutions: banking, online stores, inventory management, and CRM. Once they connect to one, it becomes hard to stop. And now a fifth, eighth, tenth service makes the entrepreneur's work easier, but users transfer data between these cloud services manually. The work turns into a nightmare.<\/p>\n

The obvious solution is to give users the ability to transfer data between cloud services. For example, importing and exporting data as files that can then be uploaded to the required service. Files are usually modified to fit the format of each service. This is more or less simple manual work, but as the number of these services grows, it becomes increasingly difficult to manage.<\/p>\n

Therefore, the next step is the API. With it, the cloud service benefits from connecting multiple services at a single point. The emergence of such an ecosystem attracts new clients with additional opportunities. A product with new functionality becomes more profitable and useful.<\/p>\n

If you create your own APIs, it attracts third-party sellers in the form of programmers who learn about your product through the API. They start building solutions based on the proposed API and earn money by automating their clients' tasks.<\/p>\n

The MyWarehouse accounting system is built on simple processes. The main focus is on working with primary documents, allowing for receiving and shipping goods, and generating business reports based on primary data. There is also data transfer, for instance to cloud accounting, and acquiring data from banking systems or retail outlets. We also work with online stores: receiving information about products and sending inventory data.<\/p>\n

\"API-t
\n<\/p>\n

A MeuArmaz\u00e9m API<\/h2>\n

\nA MeuArmaz\u00e9m \u00e9 uma plataforma que, ao longo de 10 anos de uso de API, acumulou diversas integra\u00e7\u00f5es que permitem a troca de dados, intera\u00e7\u00e3o com bancos, processamento de pagamentos e uso de telefonia externa.<\/p>\n

No primeiro ano, disponibilizamos a op\u00e7\u00e3o de exportar quaisquer dados em formato XML. Naquela \u00e9poca, os usu\u00e1rios achavam muito mais compreens\u00edvel e costumeiro manter os dados offline, em vez de em alguma nuvem, e n\u00f3s oferecemos isso. A exporta\u00e7\u00e3o era realizada manualmente a partir da interface. Portanto, n\u00e3o pod\u00edamos ainda chamar isso de API. <\/p>\n

Na mesma \u00e9poca, iniciamos uma colabora\u00e7\u00e3o com a empresa Rusagro \u2014 eles j\u00e1 utilizavam um ERP 'maduro' para planejamento de produ\u00e7\u00e3o e vendas, enquanto a carga dos vag\u00f5es nas f\u00e1bricas foi automatizada no MeuArmaz\u00e9m. Assim, surgiram as primeiras sementes de uma verdadeira API: a troca de dados entre nosso servi\u00e7o e o ERP ocorria atrav\u00e9s do envio de um grande arquivo contendo informa\u00e7\u00f5es sobre todos os tipos de documentos. <\/p>\n

Esta era uma boa op\u00e7\u00e3o para a troca de dados em lote, mas com os documentos era necess\u00e1rio tamb\u00e9m transmitir suas depend\u00eancias: informa\u00e7\u00f5es sobre produtos, contrapartes e armaz\u00e9ns. Gerar essa confus\u00e3o na exporta\u00e7\u00e3o n\u00e3o era t\u00e3o dif\u00edcil, mas analis\u00e1-la na importa\u00e7\u00e3o era bastante complicado, j\u00e1 que todos os dados chegavam em um \u00fanico pacote: informa\u00e7\u00f5es sobre novos documentos e sobre documentos j\u00e1 existentes.<\/p>\n

A primeira API XML n\u00e3o durou muito \u2014 ap\u00f3s dois anos, come\u00e7amos a reestrutur\u00e1-la. Desde o in\u00edcio de sua opera\u00e7\u00e3o, cometemos alguns erros na constru\u00e7\u00e3o da interface program\u00e1tica.<\/p>\n

\"API-t
\nComo foi realizada a API XML: ilustra\u00e7\u00e3o de um dos nossos arquitetos. A prop\u00f3sito, fique atento aos seus artigos.<\/i><\/p>\n

Aqui est\u00e3o nossos principais erros:<\/p>\n

    \n
  1. A marca\u00e7\u00e3o JAXB foi feita diretamente nos beans de entidade. Para comunica\u00e7\u00e3o com o banco de dados, usamos Hibernate, e essa mesma marca\u00e7\u00e3o JAXB foi feita nos mesmos beans. Esse erro apareceu rapidamente: qualquer atualiza\u00e7\u00e3o na estrutura de dados exigia uma notifica\u00e7\u00e3o urgente a todos que utilizavam a API, ou a constru\u00e7\u00e3o de solu\u00e7\u00f5es alternativas que garantissem a compatibilidade com a estrutura de dados anterior.<\/li>\n
  2. Az API kezdetben egy kieg\u00e9sz\u00edt\u00e9sk\u00e9nt fejl\u0151d\u00f6tt, \u00e9s eredetileg nem hat\u00e1roztuk meg, hogy a term\u00e9k melyik r\u00e9sz\u00e9t k\u00e9pezi. Arra sem gondoltunk, hogy az API valami fontos lenne, hogy sz\u00fcks\u00e9g lenne a visszafel\u00e9 kompatibilit\u00e1s fenntart\u00e1s\u00e1ra az els\u0151 \u00fcgyfelei sz\u00e1m\u00e1ra. Egy id\u0151szakban az API felhaszn\u00e1l\u00f3inak sz\u00e1ma mind\u00f6ssze 5%-\u00e1t tette ki a csek\u00e9ly \u00f6sszes felhaszn\u00e1l\u00f3nak, \u00edgy r\u00e1juk nem figyelt\u00fcnk. Az egyes\u00edtett sz\u0171r\u00e9s, amit valaha k\u00e9sz\u00edtett\u00fcnk, hozz\u00e1j\u00e1rult ahhoz, hogy minket backendk\u00e9nt kezdtek haszn\u00e1lni. Ez a sz\u0171r\u00e9s egy\u00e1ltal\u00e1n nem volt GraphQL, de hasonl\u00f3 volt \u2014 sz\u00e1mos lek\u00e9rdez\u00e9si param\u00e9teren kereszt\u00fcl m\u0171k\u00f6d\u00f6tt. Ezzel a hat\u00e9kony eszk\u00f6zzel a felhaszn\u00e1l\u00f3knak neh\u00e9z volt ellen\u00e1llni, \u00e9s a lek\u00e9rdez\u00e9seik k\u00f6zvetlen\u00fcl az online boltjaik UI-j\u00e1b\u00f3l indultak. A helyzet kellemetlen meglepet\u00e9sk\u00e9nt \u00e9rkezett, mert egy ilyen szolg\u00e1ltat\u00e1s ny\u00fajt\u00e1sa m\u00e1s d\u00edjaz\u00e1st \u00e9s egy\u00e9b meg\u00e9rt\u00e9st ig\u00e9nyel az API mint term\u00e9k tekintet\u00e9ben.<\/li>\n
  3. Mivel az API nem mint f\u0151 term\u00e9k fejl\u0151d\u00f6tt, az API dokument\u00e1ci\u00f3j\u00e1t a marad\u00e9keli alapelvek szerint k\u00e9sz\u00edtett\u00fck \u00e9s publik\u00e1ltuk \u2014 visszafejleszt\u00e9sen kereszt\u00fcl. Ez az \u00fat el\u00e9g egyszer\u0171nek \u00e9s k\u00e9nyelmesnek t\u0171nik, azonban ellent\u00e9tes a szerz\u0151d\u00e9ses munk\u00e1val. Ez akkor t\u00f6rt\u00e9nik, amikor van egy komponens egy el\u0151re be\u00e1ll\u00edtott m\u0171k\u00f6d\u00e9si s\u00e9m\u00e1val. A fejleszt\u0151 ennek megfelel\u0151en val\u00f3s\u00edtja meg, a komponens tesztel\u00e9sen megy kereszt\u00fcl, az \u00fcgyf\u00e9l egy olyan term\u00e9ket kap, amely megfelel az elemz\u0151 elk\u00e9pzel\u00e9s\u00e9nek. A visszafejleszt\u00e9s viszont olyan term\u00e9ket dob a piacra, amely csak egyszer\u0171en l\u00e9tezik: akad\u00e1lyokkal, furcsa megold\u00e1sokkal \u00e9s ker\u00e9kp\u00e1rokkal a sz\u00fcks\u00e9ges funkcionalit\u00e1s helyett. <\/li>\n
  4. Az \u00f6sszes API-n kereszt\u00fcl \u00e9rkez\u0151 lek\u00e9rdez\u00e9s \u00e1raml\u00e1s\u00e1t legfeljebb az Nginx vagy az alkalmaz\u00e1s szerver napl\u00f3jak\u00e9nt lehetett elemezni. Ez nem tette lehet\u0151v\u00e9 a szakter\u00fcletek kiemel\u00e9s\u00e9t, csak a felhaszn\u00e1l\u00f3k \u00e9s el\u0151fizet\u0151k szerinti bont\u00e1st. Ha nincs lehet\u0151s\u00e9g az alkalmaz\u00e1sok vagy \u00fcgyfelek regisztr\u00e1l\u00e1s\u00e1nak szab\u00e1lyoz\u00e1s\u00e1ra, lehetetlenn\u00e9 v\u00e1lik a helyzet elemz\u00e9se. Ez a probl\u00e9ma legkev\u00e9sb\u00e9 befoly\u00e1solta az API fejl\u0151d\u00e9s\u00e9t, ink\u00e1bb a kereslet\u00e9nek \u00e9s funkci\u00f3inak meg\u00e9rt\u00e9s\u00e9r\u0151l sz\u00f3l.<\/li>\n<\/ol>\n

    <\/p>\n

    A m\u00e1sodik k\u00eds\u00e9rlet: REST API<\/h2>\n

    \n2010-ben pr\u00f3b\u00e1ltunk egy online k\u00f6nyvel\u0151 rendszerrel, a BuhSofttal, adatcser\u00e9l\u0151 rendszert \u00e9p\u00edteni. Ez nem siker\u00fclt. Viszont az integr\u00e1ci\u00f3s folyamat sor\u00e1n megjelent egy teljes funkcionalit\u00e1s\u00fa API: egy REST-alap\u00fa adatcser\u00e9l\u0151 szolg\u00e1ltat\u00e1s, amelyben nem voltak liber\u00e1lis megk\u00f6zel\u00edt\u00e9sek, mint a RPC h\u00edv\u00e1sok. Az API-val val\u00f3 kommunik\u00e1ci\u00f3t a REST szabv\u00e1nyos m\u00f3dj\u00e1ra hoztuk, ahol a k\u00e9r\u00e9s sor\u00e1ban a l\u00e9nyeg nev\u00e9t adjuk meg, m\u00edg a v\u00e9grehajtott m\u0171veletet az http-m\u00f3dszer hat\u00e1rozza meg. Bevezett\u00fck a sz\u0171r\u00e9st a l\u00e9nyek friss\u00edt\u00e9si ideje alapj\u00e1n, \u00edgy a felhaszn\u00e1l\u00f3knak lehet\u0151s\u00e9g\u00fck ny\u00edlt a saj\u00e1t rendszereikkel val\u00f3 replik\u00e1ci\u00f3ra.<\/p>\n

    Ugyanebben az \u00e9vben megjelent az API a rakt\u00e1ri \u00e9s term\u00e9k\u00e1llom\u00e1nyok export\u00e1l\u00e1s\u00e1ra. A felhaszn\u00e1l\u00f3k sz\u00e1m\u00e1ra hozz\u00e1f\u00e9rhet\u0151v\u00e9 v\u00e1ltak az API-n kereszt\u00fcl a rendszer leg\u00e9rt\u00e9kesebb r\u00e9szei \u2014 a primer dokumentumok cser\u00e9je \u00e9s a k\u00e9szlet- \u00e9s \u00f6nk\u00f6lts\u00e9gadatok sz\u00e1m\u00edt\u00e1sa.<\/p>\n

    2015 december\u00e9ben a RetailCRM k\u00f6zz\u00e9tette az els\u0151 k\u00fcls\u0151 k\u00f6nyvt\u00e1rat, amely hozz\u00e1f\u00e9r\u00e9st biztos\u00edtott az API-nkhoz. Ezt meglehet\u0151sen akt\u00edvan haszn\u00e1lt\u00e1k, mik\u00f6zben n\u00f6vekedett a szolg\u00e1ltat\u00e1s n\u00e9pszer\u0171s\u00e9ge is, \u00e9s az API terhel\u00e9se gyorsabban n\u0151tt, mint a webes fel\u00fclet terhel\u00e9se. Egyszer csak a n\u00f6veked\u00e9s ugr\u00e1ss\u00e1 v\u00e1ltozott. <\/p>\n

    \"API-t
    \n
    \n\"API-t
    \n
    \n\u00c9s ez az ugr\u00e1s, amelyet a bal oldalon mutat\u00f3 ny\u00edl jelez, teljes megd\u00f6bben\u00e9st okozott a mi API-nkat kiszolg\u00e1l\u00f3 szervernek. Egy h\u00e9tig pr\u00f3b\u00e1ltuk kider\u00edteni, hogy ez a terhel\u00e9s pontosan mit gener\u00e1l. Kider\u00fclt, hogy ezek azok a lek\u00e9rdez\u00e9sek, amelyeket az \u00fcgyfelek front-endjei transzferek az API-nkra. K\u00f6r\u00fclbel\u00fcl 50 \u00fcgyf\u00e9l fogyasztotta el az \u00f6sszes er\u0151forr\u00e1st. Ekkor meg\u00e9rtett\u00fck egyik hib\u00e1nkat \u2014 a teljesen hi\u00e1nyz\u00f3 korl\u00e1tokat. <\/p>\n

    V\u00e9g\u00fcl bevezett\u00fck a korl\u00e1tot a p\u00e1rhuzamos lek\u00e9rdez\u00e9sek sz\u00e1m\u00e1ra. Egy fi\u00f3kb\u00f3l legfeljebb k\u00e9t lek\u00e9rdez\u00e9st lehetett egyszerre megnyitni. Ez elegend\u0151 volt a replik\u00e1ci\u00f3s m\u00f3dban val\u00f3 munk\u00e1hoz az adatok csomagolt cser\u00e9j\u00e9re. Azok sz\u00e1m\u00e1ra, akik minket backendk\u00e9nt k\u00edv\u00e1ntak haszn\u00e1lni, az\u00f3ta t\u00f6bbet kellett igazodniuk a tarif\u00e1khoz, mivel t\u00f6bb fi\u00f3k haszn\u00e1lat\u00e1ra is k\u00f6telez\u0151v\u00e9 tett\u00fck a programjaikban.<\/p>\n

    Rendet rakunk<\/h2>\n

    \nM\u00e1r 2014 \u00f3ta a megl\u00e9v\u0151 API ir\u00e1nti kereslet a v\u00e1llalkoz\u00e1s fontos r\u00e9sz\u00e9v\u00e9 v\u00e1lt, \u00e9s maga az API gener\u00e1lta a legnagyobb adatforgalmat az \u00fcgyfelekkel val\u00f3 adatcser\u00e9ben. 2015-ben elind\u00edtottuk az API rendez\u00e9s\u00e9re ir\u00e1nyul\u00f3 projektet. A JSON form\u00e1tumot v\u00e1lasztottuk az XML helyett, \u00e9s azt az el\u0151z\u0151 verzi\u00f3 megval\u00f3s\u00edt\u00e1sa sor\u00e1n felt\u00e1rt jellemz\u0151k alapj\u00e1n kezdt\u00fck el fel\u00e9p\u00edteni:<\/p>\n

      \n
    1. Verzi\u00f3kezel\u00e9si lehet\u0151s\u00e9g. A verzi\u00f3kezel\u00e9s lehet\u0151v\u00e9 teszi \u00faj verzi\u00f3k fejleszt\u00e9s\u00e9t an\u00e9lk\u00fcl, hogy az aktu\u00e1lis alkalmaz\u00e1st \u00e9rinten\u00e9, \u00e9s ne zavarja a felhaszn\u00e1l\u00f3k munk\u00e1j\u00e1t. <\/li>\n
    2. A felhaszn\u00e1l\u00f3 lehet\u0151s\u00e9ge, hogy l\u00e1ssa a metaadatokat a kapott v\u00e1laszban.<\/li>\n
    3. Nagy dokumentumok cser\u00e9j\u00e9nek lehet\u0151s\u00e9ge. Ha egy dokumentumot t\u00f6bb mint 4-5 ezer t\u00e9telnyi poz\u00edci\u00f3val dolgozunk fel, az probl\u00e9m\u00e1t jelent a szervernek: hosszan tart\u00f3 tranzakci\u00f3, hossz\u00fa http-k\u00e9r\u00e9s. Kifejlesztett\u00fcnk egy speci\u00e1lis mechanizmust, amely lehet\u0151v\u00e9 teszi a dokumentum darabokban val\u00f3 friss\u00edt\u00e9s\u00e9t \u00e9s a dokumentum egyes poz\u00edci\u00f3inak kezel\u00e9s\u00e9t, amelyek a szerverre k\u00fcldhet\u0151k.<\/li>\n
    4. Replik\u00e1ci\u00f3s eszk\u00f6z\u00f6k \u2014 ezek m\u00e1r a kor\u00e1bbi verzi\u00f3ban is jelen voltak.<\/li>\n
    5. Terhel\u00e9si korl\u00e1tok \u2014 mint az el\u0151z\u0151 verzi\u00f3ba hiba k\u00f6vetkezm\u00e9nyek\u00e9nt. Bevezett\u00fck a k\u00e9rd\u00e9sek sz\u00e1m\u00e1nak, p\u00e1rhuzamos k\u00e9r\u00e9sek sz\u00e1m\u00e1nak \u00e9s egy ip-c\u00edmr\u0151l \u00e9rkez\u0151 k\u00e9r\u00e9sek sz\u00e1m\u00e1nak korl\u00e1toz\u00e1s\u00e1t.<\/li>\n<\/ol>\n

      \nAz\u00f3ta k\u00e9t kisebb API verzi\u00f3t adtunk ki, \u00e9s n\u00e9h\u00e1ny speci\u00e1lis API-t ind\u00edtottunk, de a megk\u00f6zel\u00edt\u00e9s \u00e1ltal\u00e1ban v\u00e1ltozatlan maradt. A friss\u00edtett adatcsere-form\u00e1tum \u00e9s az \u00faj architekt\u00fara lehet\u0151v\u00e9 tette a hib\u00e1k gyorsabb jav\u00edt\u00e1s\u00e1t az API-ban.<\/p>\n

      A M\u00f3dszerek API-ja ma<\/h2>\n

      \nA M\u00f3dszerek API-ja ma sz\u00e1mos feladatot ell\u00e1t:<\/p>\n