Pracowa\u0142em ostatnio z klientem, kt\u00f3ry mia\u0142 12 mikrous\u0142ug, 8 zewn\u0119trznych API i cztery r\u00f3\u017cne sposoby autoryzacji. Ka\u017cda us\u0142uga komunikowa\u0142a si\u0119 z pozosta\u0142ymi w unikalny, \u201ew\u0142asny\u201d spos\u00f3b. Jeden zesp\u00f3\u0142 u\u017cywa\u0142 REST, inny GraphQL, a jeszcze inny wymy\u015bli\u0142 w\u0142asny protok\u00f3\u0142 na WebSocketach. Brzmi znajomo? Chaos w API to jeden z najwi\u0119kszych, a jednocze\u015bnie najmniej dostrzeganych po\u017ceraczy czasu i pieni\u0119dzy w firmach technologicznych. Ten artyku\u0142 pokazuje trzy konkretne b\u0142\u0119dy organizacyjne, kt\u00f3re powoduj\u0105, \u017ce Tw\u00f3j zesp\u00f3\u0142 programistyczny traci nawet 30% swojego potencja\u0142u.<\/p>\n
Zacznijmy od podstaw: wersjonowanie API. Wydaje si\u0119 trywialne, a jednak w praktyce firmy cz\u0119sto pope\u0142niaj\u0105 ten b\u0142\u0105d. Pami\u0119tam case startupu e-commerce, kt\u00f3ry rozwija\u0142 si\u0119 bardzo dynamicznie. Ka\u017cdy zesp\u00f3\u0142 wersjonowa\u0142 API po swojemu \u2013 jedni u\u017cywali nag\u0142\u00f3wk\u00f3w, inni parametr\u00f3w URL, a jeszcze inni po prostu nie wersjonowali wcale. Po dw\u00f3ch latach rozwoju, klient frontendowy musia\u0142 obs\u0142ugiwa\u0107 trzy r\u00f3\u017cne formaty odpowiedzi dla tego samego zasobu.<\/p>\n
Dlaczego to problem?<\/strong> Bo ka\u017cda zmiana w API wymaga\u0142a r\u0119cznego testowania i aktualizacji dokumentacji. Wprowadzenie nowej wersji oznacza\u0142o godzinne spotkania, \u017ceby ustali\u0107, co si\u0119 zmieni\u0142o. Efekt? Zamiast wdra\u017ca\u0107 nowe funkcje, programi\u015bci sp\u0119dzali czas na dogadywaniu, kt\u00f3ra wersja API jest aktywna.<\/p>\n Rozwi\u0105zanie:<\/strong> Ustalcie jeden mechanizm wersjonowania \u2013 najpro\u015bciej przez URL (np. Wielu founder\u00f3w my\u015bli: \u201eAPI to tylko interfejs, niech ka\u017cdy zesp\u00f3\u0142 robi swoje\u201d. Problem w tym, \u017ce gdy API obs\u0142uguje wiele zespo\u0142\u00f3w, szybko pojawia si\u0119 syndrom \u201eczyj to kod?\u201d. Widzia\u0142em firm\u0119, gdzie API do zam\u00f3wie\u0144 by\u0142o rozwijane przez trzy r\u00f3\u017cne zespo\u0142y: jeden robi\u0142 walidacj\u0119, drugi logik\u0119 biznesow\u0105, trzeci autoryzacj\u0119. Efekt? \u017baden zesp\u00f3\u0142 nie czu\u0142 si\u0119 odpowiedzialny za ca\u0142o\u015b\u0107. B\u0142\u0119dy w API by\u0142y naprawiane dopiero po eskalacji, a zmiany w jednej cz\u0119\u015bci psu\u0142y inn\u0105.<\/p>\n Dlaczego to problem?<\/strong> Bo brak jasnej odpowiedzialno\u015bci prowadzi do chaosu decyzyjnego. Ka\u017cdy czeka, a\u017c kto\u015b inny zrobi pierwszy krok. W efekcie czas realizacji prostych zmian wyd\u0142u\u017ca si\u0119 z dni do tygodni.<\/p>\n Rozwi\u0105zanie:<\/strong> Ka\u017cde API powinno mie\u0107 wyznaczonego \u201eopiekuna\u201d \u2013 osob\u0119 lub ma\u0142y zesp\u00f3\u0142, kt\u00f3ry odpowiada za jego jako\u015b\u0107, dokumentacj\u0119 i kompatybilno\u015b\u0107 wsteczn\u0105. Wprowad\u017acie code ownership. Niech ka\u017cda zmiana w API przechodzi przez code review tej osoby. Pozwoli to zachowa\u0107 sp\u00f3jno\u015b\u0107 i przyspieszy rozw\u00f3j.<\/p>\n By\u0107 mo\u017ce brzmi to jak frazes, ale w 2024 roku wci\u0105\u017c spotykam firmy, kt\u00f3re maj\u0105 dokumentacj\u0119 API w plikach PDF wysy\u0142anych mailem, lub gorzej \u2013 w og\u00f3le jej nie maj\u0105. Jeden z moich klient\u00f3w, skalowalna platforma SaaS, mia\u0142 dokumentacj\u0119 napisan\u0105 w Google Docs, kt\u00f3ra odbiega\u0142a od rzeczywisto\u015bci o 6 miesi\u0119cy. Nowi programi\u015bci musieli sp\u0119dza\u0107 pierwsze dwa tygodnie na reverse engineeringu API, \u017ceby zrozumie\u0107, jak faktycznie dzia\u0142a.<\/p>\n Dlaczego to problem?<\/strong> Bo z\u0142a dokumentacja to strata czasu i ryzyko b\u0142\u0119d\u00f3w. Programista, kt\u00f3ry nie ma jasno\u015bci, jakie parametry akceptuje endpoint, b\u0119dzie testowa\u0142 na \u015blepo. Dochodzi do sytuacji, w kt\u00f3rych zamiast pisa\u0107 kod, ludzie sp\u0119dzaj\u0105 czas na czytaniu nieaktualnych notatek.<\/p>\n Rozwi\u0105zanie:<\/strong> U\u017cywajcie narz\u0119dzi takich jak Swagger\/OpenAPI, Postman Collections czy Stoplight, kt\u00f3re automatycznie generuj\u0105 dokumentacj\u0119 z kodu. Wprowad\u017acie zasad\u0119: ka\u017cda zmiana w API musi by\u0107 natychmiast odzwierciedlona w dokumentacji. Lepiej: zautomatyzujcie to, aby dokumentacja by\u0142a generowana przy ka\u017cdym deployu. To oszcz\u0119dza setki roboczogodzin rocznie.<\/p>\n Chaos w API to nie tylko problem techniczny \u2013 to problem organizacyjny, kt\u00f3ry kosztuje czas, pieni\u0105dze i frustracj\u0119 zespo\u0142u. Wprowadzenie sp\u00f3jnej strategii wersjonowania, jasnych odpowiedzialno\u015bci i automatycznej dokumentacji to trzy proste kroki, kt\u00f3re mog\u0105 zwi\u0119kszy\u0107 produktywno\u015b\u0107 Twojego zespo\u0142u IT o kilkana\u015bcie procent. W JurskiTech cz\u0119sto widzimy, \u017ce firmy koncentruj\u0105 si\u0119 na nowych technologiach, a zapominaj\u0105 o podstawach \u2013 to w\u0142a\u015bnie one s\u0105 fundamentem szybkiego i efektywnego rozwoju.<\/p>\n","protected":false},"excerpt":{"rendered":" Wst\u0119p Pracowa\u0142em ostatnio z klientem, kt\u00f3ry mia\u0142 12 mikrous\u0142ug, 8 zewn\u0119trznych API i cztery r\u00f3\u017cne sposoby autoryzacji. Ka\u017cda us\u0142uga komunikowa\u0142a si\u0119 z pozosta\u0142ymi w unikalny, \u201ew\u0142asny\u201d spos\u00f3b. Jeden zesp\u00f3\u0142 u\u017cywa\u0142 REST, inny GraphQL, a jeszcze inny wymy\u015bli\u0142 w\u0142asny protok\u00f3\u0142 na WebSocketach. Brzmi znajomo? Chaos w API to jeden z najwi\u0119kszych, a jednocze\u015bnie najmniej dostrzeganych po\u017ceraczy<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[422,483,336,132],"class_list":["post-1685","post","type-post","status-publish","format-standard","hentry","category-warto-wiedziec","tag-api-przegladarki","tag-efektywnosc-it","tag-modern-web-development","tag-zarzadzanie-zespolem"],"_links":{"self":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts\/1685","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/comments?post=1685"}],"version-history":[{"count":0,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/posts\/1685\/revisions"}],"wp:attachment":[{"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/media?parent=1685"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/categories?post=1685"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/news.jurskitech.pl\/blog\/wp-json\/wp\/v2\/tags?post=1685"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\/v1\/orders<\/code>). Wprowad\u017acie polityk\u0119: ka\u017cda zmiana niekompatybilna wstecz wymaga nowej wersji. Dokumentujcie to automatycznie (OpenAPI\/Swagger). Dzi\u0119ki temu zesp\u00f3\u0142 oszcz\u0119dza godziny tygodniowo.<\/p>\n2. Niejasne odpowiedzialno\u015bci za API<\/h2>\n
3. Nieaktualna lub brak dokumentacji API<\/h2>\n
Podsumowanie<\/h2>\n