Predstavte si, že potrebujete niečo vytvoriť, čo by malo komunikovať prostredníctvom rôznych webservicov, cez API a pod. Že to je easy? Kiež by.
Pravdepodobne ste ešte asi neskúšali vytvoriť integráciu podacieho hárku od Slovenskej pošty. Tu by človek čakal, že bude všetko fungovať tak ako má, ale nakoniec zistí, že život by bol jednoduhší, keby radšej žiadnu "API" pre ich služby, radšej ani nemali.
Poďme ale k príkladu
Elektronický podací hárok, ako už hovorí jeho pomenovanie, je vlastne elektronické podanie nejakého zoznamu balíčkov, ktoré chcete poslať. Takže si vytvoríte podací hárok a do neho následne navkladáte balíčky, alebo položky, ktoré s ním súvisia.
Odmysliac si, že pre každý druh poštovej zásielky potrebujete iný EPH, písať asi nebudem. Je to trochu choré, ale asi to má svoj dôvod niekde na pozadí. Snáď. Verím tomu, že je to tak. Takže si vytvoríte tento hárok, pričom pošlete veľmi jednoduchý request. V tom predsa nie je nič hrozné nie? Zatiaľ nie.
Teda, pokiaľ sa nechcete pozrieť na to, akým spôsobom je vytvorená dokumentácia pre api, ktorú ponúka slov. pošta.
Už pri pohľade na obrázok je jasné, že niečo ako štandardizovaný výstup, developerom na slov. pošte nič nehovorí. Používanie vecí ako Swagger alebo iný dokumentovací nástroj je niečo, čo tiež nepoznajú a nemajú ani v úmysle použiť.
Takže vo svojej podstate, ani neviete, na čo sa pozeráte. Povedali by ste, že toto je štruktúra pre JSON? Pre XML? Alebo pre čo konkrétne? Skúsme teda iný "podobný" zápis, napríklad keď už sme pochopili, že niekde má byť nejaký sheet().
Tiež máte pocit, že tu zasa nevidno niečo normálne, na čo je asi 99,99% developerov naučených? Ale skúsme teda presnejšie vysvetliť o čo ide. A potom prejdeme k ďalšiemu zázraku, ktorý moja hlava nijako nepobrala.
Vo svojej podstate, celý tento zápis z vyššie zobrazených náhľadov znamená, že máte urobiť JSON, kde vlastne pošlete dáta v tejto podobe:
{
"sheet": {
"parcel_category": "ek",
"sender": {
"name": "Anička Jurkovičová",
"organization": "Firma ABCD",
"street": "Partizánska cesta 9",
"city": "Banská Bystrica",
"zip": "97401",
"country": "SK",
"phone": "+421999999999",
"email": "anicka.jurkovicova@firmaabcd.sk"
},
"reception_method": "post",
"payment_type": "fa",
"own_parcel_numbers": true,
"contract": true
}
}Jediné, čo je pozitívne je, že je to aspoň na konci ich dokumentácie v príkladoch, že je to vlastne JSON formát, ktorý už dáva väčší zmysel ako ten nezmysel z ich divnými "metódami", či čo to chce vôbec byť za zápis.
Držte si klobúky, ideme na to...
Takže vo finále už viete, ako vyrobiť podací hárok. Čo však ak už nejaký podací hárok vytvorený je a chcete na ňom ešte niečo zmeniť? No. Zoberme si príklad, kedy vytvárate rozšírenie nad niečím, čo už funguje, to znamená, že už v minulosti boli posielané nejaké zásielky a chcete mať v systéme o nich prehľad.
Očakávate, že by vám API, ktorá je prepojená s vaším účtom, bude schopná tieto informácie poskytnúť na nejakom rozumnom endpoint-e, napríklad /sheets ... Také bolo aj moje očakávanie, kým som na danom endpointe nedostal chybovú hlášku, že taká adresa vôbec neexistuje.
Áno, existujú tie, kde posielate dáta, kde pristupujete k jednotlivým podacím lístkom, ale aby ste sa vedeli dostať k zoznamu toho, čo už existuje? Čo sa ignoranta ste, že chcete vidieť niečo z minulosti, k čomu ste si nemali šancu nikde uložiť lokálne referenciu aby ste to vedeli použiť niekedy v budúcnosti?
Takže máte endpointy, kde dokážete niečo vytvoriť, ale vylistovať si zoznam toho, čo ste vytvorili? Načo takú blbosť? Kto by niekedy niečo také chcel? Kto to kedy videl, aby ste napríklad v nejakom eshope videli nejaké svoje staršie objednávky nie? Kto by sa tým obťažovať vôbec zaoberať?
A tak môžete len dúfať, že klient bude mať dosť nervov na to, aby si všetky svoje podacie lístky manuálne "registroval", aby k nim vedel pristúpiť.
Tiež vám to príde choré, či to som len jak úplný debil?