{"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\/pl\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"Pisali\u015bmy API \u2014 rozpad\u0142 si\u0119 XML (dwa)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Pierwsze API MojeSklepu powsta\u0142o 10 lat temu. Przez ca\u0142y ten czas pracujemy nad istniej\u0105cymi wersjami API oraz opracowujemy nowe. A kilka wersji API ju\u017c zd\u0105\u017cy\u0142o trafi\u0107 do zapomnienia. <\/p>\n

W tym artykule b\u0119dzie wiele informacji: jak powstawa\u0142o API, po co jest potrzebne us\u0142udze w chmurze, co daje u\u017cytkownikom, na jakie pu\u0142apki natrafili\u015bmy oraz co chcemy robi\u0107 dalej.
\n<\/a><\/noindex>
\nNazywam si\u0119 Oleg Alekseev oalexeev<\/a><\/noindex>, jestem dyrektorem technicznym i wsp\u00f3\u0142za\u0142o\u017cycielem MojeSklepu. <\/p>\n

Po co tworzy\u0107 API dla us\u0142ugi<\/h2>\n

\nNasi klienci, a jest ich dziesi\u0105tki tysi\u0119cy, aktywnie korzystaj\u0105 z rozwi\u0105za\u0144 w chmurze: bankowo\u015bci, sklep\u00f3w internetowych, prowadzenia gospodarki magazynowej, CRM. Po pod\u0142\u0105czeniu do jednego \u2014 trudno si\u0119 zatrzyma\u0107. I oto pi\u0105ta, \u00f3sma, dziesi\u0105ta us\u0142uga sprawia, \u017ce praca przedsi\u0119biorcy staje si\u0119 \u0142atwiejsza, ale dane mi\u0119dzy tymi us\u0142ugami s\u0105 przenoszone r\u0119cznie. Praca zamienia si\u0119 w koszmar.<\/p>\n

Oczywistym rozwi\u0105zaniem jest umo\u017cliwienie u\u017cytkownikom przekazywania danych mi\u0119dzy us\u0142ugami w chmurze. Na przyk\u0142ad importowanie i eksportowanie danych w postaci plik\u00f3w, kt\u00f3re nast\u0119pnie mo\u017cna za\u0142adowa\u0107 do odpowiedniej us\u0142ugi. Pliki zazwyczaj dostosowuje si\u0119 do formatu ka\u017cdej us\u0142ugi. To bardziej lub mniej prosta r\u0119czna praca, ale w miar\u0119 wzrostu liczby tych us\u0142ug staje si\u0119 to coraz trudniejsze.<\/p>\n

Dlatego nast\u0119pnym krokiem jest API. Dzi\u0119ki temu us\u0142uga w chmurze zyskuje na tym, \u017ce \u0142\u0105czy kilka us\u0142ug w jednym punkcie. Pojawienie si\u0119 takiego ekosystemu przyci\u0105ga nowych klient\u00f3w dzi\u0119ki dodatkowym mo\u017cliwo\u015bciom. Produkt z now\u0105 funkcjonalno\u015bci\u0105 staje si\u0119 bardziej op\u0142acalny i u\u017cyteczny.<\/p>\n

Je\u015bli tworzysz w\u0142asne interfejsy programistyczne, przyci\u0105gasz zewn\u0119trznych sprzedawc\u00f3w w postaci programist\u00f3w, kt\u00f3rzy poznaj\u0105 Tw\u00f3j produkt dzi\u0119ki API. Zaczynaj\u0105 budowa\u0107 rozwi\u0105zania na podstawie oferowanego API i zarabiaj\u0105 pieni\u0105dze na automatyzacji zada\u0144 swoich klient\u00f3w.<\/p>\n

System ksi\u0119gowy MojeSklepu oparty jest na prostych procesach. G\u0142\u00f3wne zadanie to praca z dokumentami \u017ar\u00f3d\u0142owymi, mo\u017cliwo\u015b\u0107 przyjmowania i wydawania towaru, uzyskiwanie raport\u00f3w dla biznesu na podstawie dokument\u00f3w \u017ar\u00f3d\u0142owych. Ponadto wyst\u0119puje przekazywanie danych, na przyk\u0142ad do chmurowej ksi\u0119gowo\u015bci, oraz ich pozyskiwanie z system\u00f3w bankowych lub punkt\u00f3w sprzeda\u017cy. Ponadto wsp\u00f3\u0142pracujemy z sklepami internetowymi: uzyskujemy informacje o produktach i przesy\u0142amy dane o stanach magazynowych.<\/p>\n

\"Pisali\u015bmy
\n<\/p>\n

Pierwsze API MojeMagazyny<\/h2>\n

\nPrzez 10 lat pracy MojeMagazyny z API zgromadzili\u015bmy r\u00f3\u017cnorodne integracje, kt\u00f3re umo\u017cliwiaj\u0105 wymian\u0119 danych, wsp\u00f3\u0142prac\u0119 z bankami, realizacj\u0119 p\u0142atno\u015bci oraz wykorzystanie telefonii zewn\u0119trznej.<\/p>\n

W pierwszym roku umo\u017cliwili\u015bmy eksport dowolnych danych w formacie XML. W\u00f3wczas u\u017cytkownikom \u0142atwiej by\u0142o i wygodniej trzyma\u0107 dane offline, a nie w jakiej\u015b tam chmurze, wi\u0119c im to zapewnili\u015bmy. Eksport uruchamiano r\u0119cznym eksportem z interfejsu. W\u00f3wczas API nie mo\u017cna by\u0142o jeszcze tak nazwa\u0107. <\/p>\n

Wtedy zacz\u0119li\u015bmy wsp\u00f3\u0142prac\u0119 z firm\u0105 Rusagro \u2014 oni ju\u017c korzystali z 'doros\u0142ego' ERP do planowania produkcji i sprzeda\u017cy, a my zautomatyzowali\u015bmy za\u0142adunek wagon\u00f3w w MoimMagazynie. Tak pojawi\u0142y si\u0119 pierwsze zal\u0105\u017cki prawdziwego API: wymiana mi\u0119dzy naszym serwisem a ERP odbywa\u0142a si\u0119 poprzez przesy\u0142anie du\u017cego pliku z danymi we wszystkich typach dokument\u00f3w. <\/p>\n

To niez\u0142a opcja dla wsadowej wymiany danych, ale razem z dokumentami trzeba by\u0142o przekazywa\u0107 ich zale\u017cno\u015bci: informacje o towarach, kontrahentach i magazynach. Tak\u0105 chaotyczn\u0105 struktur\u0119 \u0142atwo jest wygenerowa\u0107 podczas eksportu, ale do\u015b\u0107 trudno zanalizowa\u0107 podczas importu, poniewa\u017c w jednym pakiecie przychodz\u0105 wszystkie informacje: zar\u00f3wno o nowych dokumentach, jak i ju\u017c istniej\u0105cych.<\/p>\n

Pierwsze XML API nie przetrwa\u0142o d\u0142ugo \u2014 dwa lata p\u00f3\u017aniej zacz\u0119li\u015bmy jego przebudow\u0119. Ju\u017c na pocz\u0105tku jego dzia\u0142ania pope\u0142nili\u015bmy kilka b\u0142\u0119d\u00f3w przy budowie interfejsu programowania.<\/p>\n

\"Pisali\u015bmy
\nJak powstawa\u0142o XML API: ilustracja stworzona przez jednego z naszych architekt\u00f3w. Przy okazji, czekajcie na jego artyku\u0142y.<\/i><\/p>\n

Oto nasze g\u0142\u00f3wne b\u0142\u0119dy:<\/p>\n

    \n
  1. Rozmieszczenie JAXB by\u0142o zrobione bezpo\u015brednio na entity beans. Do komunikacji z baz\u0105 danych u\u017cywamy Hibernate, a na tych samych beanach zrobiono rozmieszczenie JAXB. Ten b\u0142\u0105d ujawnia\u0142 si\u0119 niemal natychmiast: ka\u017cda aktualizacja struktury danych wymaga\u0142a natychmiastowego powiadomienia wszystkich, kt\u00f3rzy korzystali z API, lub stworzenia rozwi\u0105za\u0144, kt\u00f3re zapewnia\u0142yby zgodno\u015b\u0107 z poprzedni\u0105 struktur\u0105 danych.<\/li>\n
  2. API rozwija\u0142 si\u0119 jako pewnego rodzaju dodatek, i pocz\u0105tkowo nie zdefiniowali\u015bmy, jak\u0105 cz\u0119\u015b\u0107 produktu on stanowi. Nie zastanawiali\u015bmy si\u0119 r\u00f3wnie\u017c, czy API jest czym\u015b wa\u017cnym, czy konieczne jest utrzymywanie zgodno\u015bci wstecznej dla jego pierwszych klient\u00f3w. Na pewnym etapie liczba u\u017cytkownik\u00f3w API stanowi\u0142a oko\u0142o 5% og\u00f3lnej liczby, i nie zwracali\u015bmy na nich uwagi. Wprowadzona wtedy uniwersalna filtracja spowodowa\u0142a, \u017ce zacz\u0119to nas wykorzystywa\u0107 jako backend. Ta filtracja by\u0142a zupe\u0142nie inna ni\u017c GraphQL, ale co\u015b w tym stylu \u2014 dzia\u0142a\u0142a za po\u015brednictwem wielu parametr\u00f3w w zapytaniach. Z takim pot\u0119\u017cnym narz\u0119dziem u\u017cytkownikom by\u0142o trudno si\u0119 oprze\u0107 i zacz\u0119li wysy\u0142a\u0107 zapytania bezpo\u015brednio z UI swoich sklep\u00f3w internetowych. Sytuacja sta\u0142a si\u0119 nieprzyjemnym zaskoczeniem, poniewa\u017c \u015bwiadczenie takiej us\u0142ugi powinno wymaga\u0107 innego modelu cenowego i zupe\u0142nie innego postrzegania samego API jako produktu.<\/li>\n
  3. Poniewa\u017c API rozwija\u0142o si\u0119 nie jako podstawowy produkt, dokumentacja API by\u0142a tworzona i publikowana w trybie dora\u017anym \u2014 poprzez in\u017cynieri\u0119 wsteczn\u0105. Ten spos\u00f3b wydaje si\u0119 do\u015b\u0107 prosty i wygodny, ale stoi w sprzeczno\u015bci z prac\u0105 na podstawie kontraktu. To sytuacja, gdy istnieje pewny komponent z preinstalowanym schematem dzia\u0142ania. Programista wdra\u017ca go zgodnie z tym schematem i zadaniem, komponent przechodzi testy, a klient otrzymuje produkt, kt\u00f3ry odpowiada zamys\u0142owi analityka. In\u017cynieria wsteczna natomiast wprowadza na rynek produkt, kt\u00f3ry po prostu istnieje: z obej\u015bciami, dziwnymi rozwi\u0105zaniami i wynalazkami zamiast potrzebnej funkcjonalno\u015bci. <\/li>\n
  4. Ca\u0142y strumie\u0144 zapyta\u0144, kt\u00f3ry przychodzi\u0142 przez API, mo\u017cna by\u0142o analizowa\u0107 jedynie jako log Nginx\u2019a lub serwera aplikacji. To nie pozwala\u0142o na wyodr\u0119bnienie obszar\u00f3w tematycznych, chyba \u017ce rozdzieli\u0107 je wed\u0142ug u\u017cytkownik\u00f3w i subskrybent\u00f3w. Je\u015bli nie ma mo\u017cliwo\u015bci regulowania rejestracji aplikacji lub klient\u00f3w, analiza sytuacji staje si\u0119 niemo\u017cliwa. Ten problem w najmniejszym stopniu wp\u0142yn\u0105\u0142 na rozw\u00f3j API, bardziej dotyczy zrozumienia jego popularno\u015bci i funkcjonalno\u015bci.<\/li>\n<\/ol>\n

    <\/p>\n

    Pr\u00f3ba numer dwa: REST API<\/h2>\n

    \nW 2010 roku pr\u00f3bowali\u015bmy zbudowa\u0107 system wymiany z internetow\u0105 ksi\u0119gowo\u015bci\u0105 \u2014 BuchSoft. Nie uda\u0142o si\u0119. Jednak w trakcie integracji powsta\u0142o pe\u0142noprawne API: us\u0142ug\u0119 REST do wymiany, w kt\u00f3rej nie by\u0142o dowolno\u015bci, jak w przypadku wywo\u0142a\u0144 RPC. Ca\u0142a komunikacja z API zosta\u0142a sprowadzona do standardowego trybu REST: w ci\u0105gu \u017c\u0105dania znajduje si\u0119 nazwa encji, a operacja, kt\u00f3ra jest z ni\u0105 przeprowadzana, jest okre\u015blana za pomoc\u0105 metody http. Dodali\u015bmy filtracj\u0119 wed\u0142ug momentu aktualizacji encji, dzi\u0119ki czemu u\u017cytkownicy mieli mo\u017cliwo\u015b\u0107 budowania replikacji ze swoimi systemami.<\/p>\n

    W tym samym roku pojawi\u0142o si\u0119 API do eksportu stan\u00f3w magazynowych i towarowych. U\u017cytkownicy zyskali dost\u0119p \u0447\u0435\u0440\u0435\u0437 API do najbardziej warto\u015bciowych cz\u0119\u015bci systemu \u2014 wymiany dokument\u00f3w pierwotnych oraz danych kalkulacyjnych dotycz\u0105cych stan\u00f3w i koszt\u00f3w towar\u00f3w.<\/p>\n

    W grudniu 2015 roku RetailCRM opublikowa\u0142 pierwsz\u0105 zewn\u0119trzn\u0105 bibliotek\u0119 dost\u0119pu do naszego API. Zacz\u0119to j\u0105 do\u015b\u0107 intensywnie wykorzystywa\u0107, a popularno\u015b\u0107 us\u0142ugi og\u00f3lnie ros\u0142a, obci\u0105\u017cenie API ros\u0142o szybciej ni\u017c obci\u0105\u017cenie interfejsu webowego. Pewnego dnia wzrost przekszta\u0142ci\u0142 si\u0119 w skok obci\u0105\u017cenia. <\/p>\n

    \"Pisali\u015bmy
    \n
    \n\"Pisali\u015bmy
    \n
    \nI ten skok, kt\u00f3ry pokazuje strza\u0142ka po lewej stronie, wprawi\u0142 w totalne zdziwienie serwer obs\u0142uguj\u0105cy nasze API. Przez tydzie\u0144 analizowali\u015bmy, co dok\u0142adnie generuje to obci\u0105\u017cenie. Okaza\u0142o si\u0119, \u017ce to te same zapytania, kt\u00f3re by\u0142y przesy\u0142ane do naszego API z front\u00f3w klient\u00f3w. Ca\u0142o\u015b\u0107 wygenerowa\u0142o oko\u0142o 50 klient\u00f3w. Wtedy zrozumieli\u015bmy jeden z naszych b\u0142\u0119d\u00f3w \u2014 ca\u0142kowity brak limit\u00f3w. <\/p>\n

    W rezultacie wprowadzili\u015bmy limit na liczb\u0119 jednoczesnych zapyta\u0144. Z jednego konta mo\u017cna by\u0142o jednocze\u015bnie otworzy\u0107 nie wi\u0119cej ni\u017c dwa zapytania. To wystarczaj\u0105co du\u017co, aby dzia\u0142a\u0107 w trybie replikacji do wymiany danych w trybie paczkowym. A ci, kt\u00f3rzy chcieli wykorzysta\u0107 nas jako backend, od tego momentu musieli bardziej dostosowa\u0107 si\u0119 do taryf, poniewa\u017c wprowadzili w swoich programach obs\u0142ug\u0119 wielu kont.<\/p>\n

    Wprowadzamy porz\u0105dek<\/h2>\n

    \nJu\u017c od 2014 roku zapotrzebowanie na istniej\u0105ce API sta\u0142o si\u0119 wa\u017cn\u0105 cz\u0119\u015bci\u0105 biznesu, a samo API generowa\u0142o najwi\u0119ksz\u0105 ilo\u015b\u0107 danych w wymianie informacji z klientami. W 2015 roku uruchomili\u015bmy projekt porz\u0105dkowania API. Wybrali\u015bmy jako format JSON zamiast XML i zacz\u0119li\u015bmy budowa\u0107 go na podstawie szczeg\u00f3lnych cech, kt\u00f3re ujawnili\u015bmy podczas wdra\u017cania poprzedniej wersji:<\/p>\n

      \n
    1. Mo\u017cliwo\u015b\u0107 zarz\u0105dzania wersjami. Wersjonowanie umo\u017cliwia rozwijanie nowej wersji bez wp\u0142ywania na istniej\u0105c\u0105 aplikacj\u0119 i nie zak\u0142\u00f3caj\u0105c pracy u\u017cytkownik\u00f3w. <\/li>\n
    2. Mo\u017cliwo\u015b\u0107, aby u\u017cytkownik widzia\u0142 metadane w odpowiedzi, kt\u00f3r\u0105 otrzymuje.<\/li>\n
    3. Mo\u017cliwo\u015b\u0107 wymiany du\u017cych dokument\u00f3w. Je\u015bli przetwarzamy dokument z ilo\u015bci\u0105 pozycji wi\u0119ksz\u0105 ni\u017c 4-5 tysi\u0119cy, staje si\u0119 to problemem dla serwera: d\u0142uga transakcja, d\u0142ugi \u017c\u0105danie http. Zbudowano specjalny mechanizm, kt\u00f3ry pozwala aktualizowa\u0107 dokument cz\u0119\u015bciami i zarz\u0105dza\u0107 poszczeg\u00f3lnymi pozycjami tego dokumentu, wysy\u0142aj\u0105c je na serwer.<\/li>\n
    4. Narz\u0119dzia do replikacji \u2014 by\u0142y tak\u017ce w poprzedniej wersji.<\/li>\n
    5. Limity obci\u0105\u017cenia \u2014 jako dziedzictwo problem\u00f3w, na kt\u00f3re natrafiono w poprzedniej wersji. Wprowadzono limity na liczb\u0119 \u017c\u0105da\u0144 w danym czasie, liczb\u0119 r\u00f3wnoleg\u0142ych \u017c\u0105da\u0144 i \u017c\u0105da\u0144 z jednego adresu ip.<\/li>\n<\/ol>\n

      \nOd tego czasu wydali\u015bmy dwie minorowe wersje API i uruchomili\u015bmy kilka specjalistycznych API, ale og\u00f3lny podej\u015bcie pozosta\u0142o bez zmian. Zaktualizowany format wymiany i nowa architektura pozwoli\u0142y szybciej poprawia\u0107 braki w API.<\/p>\n

      API MojeMagazyny dzi\u015b<\/h2>\n

      \nDzi\u015b API MojeMagazyny rozwi\u0105zuje wiele zada\u0144:<\/p>\n