Znasz to uczucie? Szef mówi: „Pobierz tylko listę fundacji z rządowego portalu, to przecież chwila roboty, mają API”. Wchodzisz w to pełen optymizmu, a wychodzisz trzy dni później, z zapasem kawy na wyczerpaniu i przekonaniem, że internet to czasem bardzo dziwne miejsce...

Dziś opowiem Wam o mojej przygodzie z API portalu dane.gov.pl. Zapnijcie pasy, bo to będzie wycieczka przez architektoniczne pole minowe.
Dla Fundacji, z którą współpracuję, miałem pobierać i pracować z danymi "Rejestr fundacji nadzorowanych przez Ministra Klimatu i Środowiska". Byłem pewny, że pracując na danych "rządowych" będzie to lekkie, łatwe i przyjemne - nic bardziej mylnego.

Magiczne liczby zamiast logiki - w świecie nowoczesnych technologii spodziewałbyś się adresu typu: /ministerstwo-klimatu/fundacje [lub /id_instytucji/id_zasobu] Proste, prawda?

W rzeczywistości dane ukryte są pod numerem 1034419. To nie jest kod dostępu do skarbca, to po prostu „zasób”. Jeśli Ministerstwo jutro zaktualizuje plik, dostanie on nowy numer, a Twoja aplikacja... cóż, będzie dalej uparcie wyświetlać dane z zeszłego roku, o ile w ogóle nie rzuci błędem. W tym systemie nie szukasz instytucji – szukasz anonimowej paczki danych.

Enigma w formacie JSON

Kiedy już przebijesz się przez nagłówki, wita Cię on: JSON-Matrioszka.
Zamiast dostać elegancki obiekt:
"nazwa": "Fundacja Aktywne Koty",
dostajesz labirynt: data -> attributes -> col4 -> val.

Dlaczego col4? Bo tak. Bo API nie serwuje bazy danych, ono serwuje... widok arkusza Excel. Jeśli ktoś w urzędzie przesunie kolumnę w lewo, Twoja wyszukiwarka fundacji nagle zacznie wyświetlać numery kont bankowych zamiast nazw. Zero semantyki, czysta partyzantka.
Mój ulubiony moment? Wyświetlamy listę, klikasz w fundację, żeby zobaczyć adres, i... Błąd 404. API twierdzi, że rekord, który przed chwilą nam samo pokazało, nie istnieje.
Okazało się, że identyfikatory rekordów żyją własnym życiem. Czasem zaczynają się od cyfry, co wysadza w powietrze JavaScript (SyntaxError), a czasem wymagają od PHP magicznej flagi FOLLOWLOCATION, bo serwer lubi robić niezapowiedziane wycieczki po adresach URL.

Kiedy już przestaliśmy rzucać klawiaturą, musieliśmy przejść do konkretów.

Oto trzy techniczne „hacki”, które sprawiły, że nasza wyszukiwarka w ogóle ruszyła z miejsca: mostek PHP (Proxy), czyli tarcza anty-CORS
Przeglądarki nienawidzą pytać o dane bezpośrednio z innych serwerów (blokada CORS). Zamiast walczyć z nagłówkami Ministerstwa, postawiliśmy własny „mostek” w PHP. Zaleta: nasz skrypt fetch_api stał się bezpiecznym pośrednikiem. Trik: Dodaliśmy flagę CURLOPT_FOLLOWLOCATION. Bez niej niektóre zapytania o szczegóły fundacji kończyły się pustką, bo API lubiło po cichu przekierować nas na inny adres, o którym zapomniało wspomnieć. 

Debouncing, czyli nie „męcz” serwera - początkowo wyszukiwarka chciała pytać API o każdą wpisaną literę. Wpisujesz „Warszawa” – 8 zapytań. Przy tak ociężałym API to przepis na katastrofę. Rozwiązanie: wprowadziliśmy searchTimeout. Skrypt czeka 400ms. Jeśli przestaniesz pisać – dopiero wtedy strzela do serwera. To uratowało płynność interfejsu i prawdopodobnie zapobiegło zablokowaniu naszego IP przez rządowe firewalle.

Dynamiczne "bezpieczne" ID - to był nasz największy sukces w walce z błędami JS. Ponieważ identyfikatory w API bywają numeryczne, ale zachowują się jak tekst, każde wywołanie funkcji showDetails ubraliśmy w cudzysłowy: onclick="showDetails('${rowId}')".
Dlaczego? Bo JavaScript widząc ID typu 000123, potraktuje je jako liczbę ósemkową, a przy 123abc po prostu wyrzuci błąd składni. Stringowanie danych to w tym API jedyna droga do stabilności.

„Droga przez mękę” nauczyła nas jednego: nie ma złych danych, są tylko niefortunne formaty. Nasza praca polegała na zbudowaniu „tłumacza”, który z biurokratycznego bełkotu col1, col2, col3 stworzył czytelną, błyskawiczną wyszukiwarkę. Morał? Jeśli API rzuca Ci kłody pod nogi, zbuduj z nich schody. Albo przynajmniej porządny mostek w PHP.

Jak przetrwać i nie zwariować?

Z tej lekcji wyciągnęliśmy trzy złote zasady:
Stosuj Adaptery: Nigdy nie wpuszczaj col4 do swojego kodu. Od razu zamień to na nazwa. Dzięki temu, gdy API się zmieni, poprawisz tylko jedną linijkę, a nie cały projekt.
Cudzysłowy to Twoja tarcza: Przekazuj ID zawsze jako tekst. showDetails('123') uratuje Cię przed błędami składni, o których nie śniło się filozofom.
Cache to konieczność: Nie ufaj zewnętrznemu API. Jeśli możesz, pobierz te dane do siebie i serwuj je z własnej, czystej bazy.

Praca z danymi publicznymi to misja cywilizacyjna. Dane są cenne, ale ich forma... cóż, bywa „niefortunna”. Jeśli budujesz takie systemy – błagam, myśl o programistach, którzy będą z tego korzystać po nocach. 
A jeśli jesteś programistą i właśnie walczysz z zasobem o numerze X – nie jesteś sam.

Smutne podsumowanie: API czy tylko konwerter plików?

Po dniach walki z kodem, odpowiedź stała się jasna: pod maską portalu dane.gov.pl nie bije serce nowoczesnej, zintegrowanej, usystematyzowanej bazy danych. To raczej gigantyczny, cyfrowy kontener na pliki z Excela.

Mechanizm jest bolesny w swojej prostocie:
  • Urzędnik przygotowuje arkusz (CSV/XLS), wrzucając dane tak, jak mu wygodnie (stąd te nieszczęsne col1, col2).
  • System "połyka" ten plik i bez żadnej głębszej analizy czy walidacji, zamienia go w JSON-a.
  • Programista (czyli my) dostaje ten wynik i musi bawić się w cyfrowego archeologa, próbując odgadnąć, co autor miał na myśli.
To dlatego identyfikatory się zmieniają, kolumny nie mają nazw, a my musimy stosować "hacki", żeby aplikacja w ogóle wiedziała, o czym mowa. Nie budujemy aplikacji na fundamencie – budujemy ją na ruchomych piaskach urzędniczych arkuszy.

Morał dla czytelników: Jeśli planujesz pracę z danymi publicznymi, nie zakładaj, że po drugiej stronie jest inżynier. Zakładaj, że jest tam człowiek z Excelem, który po prostu chce już iść do domu. Twoim zadaniem jest zbudowanie filtra, który ten chaos zamieni w coś użytecznego.