eHUB má nové API pro Publishery

Minulý týden jsme uvedli do provozu nové API pro Publishery. Z pohledu uživatele tímto krokem definitivně přecházíme na vlastní softwarové řešení. Díky tomu budeme moci mnohem lépe reagovat na přání a technické požadavky našich partnerů a rychleji implementovat nové funkce.

Při vývoji jsme jako vždy kladli důraz na čistý objektový návrh. Automatické testy jsou samozřejmostí. Nové API běží na PHP 7.2 a opět jsme sáhli po osvědčeném Nette, jehož oficiálním partnerem jsme se před několika měsíci stali. Podporujeme tak další vývoj tohoto oblíbeného PHP frameworku, který umožní i nám držet krok s technologickým pokrokem a poskytovat našim partnerům rychlý a bezpečný software.

Ale zpět k eHUB API. Inspirovali jsme se stylem architektury REST. API je tedy orientováno datově, nikoli procedurálně. Každý endpoint je charakterizován url, které představuje přístup ke zdroji (dat). Pro lepší identifikaci zdroje a jednotný přístup v rámci celého ekosystému aplikací eHUB jsme přistoupili k mírné změně názvosloví. Týká se to termínu používaného pro reklamní prvky, které má k dispozici Publisher. Místo dříve používaného slůvka banner, nyní používáme obecnější termín creative. Nejdůležitější reklamní prvek totiž dávno není pouze grafický banner, ale jejich škála je mnohem bohatší a stále se rozšiřuje. Endpoint pro práci s reklamními prvky má tedy URL zakončené slovem creatives a identifikátor konkrétního reklamního prvku je creativeId. Pro pojmenování parametrů používáme notaci camelCase.

Url nám tedy slouží pro identifikaci zdroje. Operace, která bude s daty provedena, je v naší implementaci představována použitou HTTP metodou. Například pomocí metody GET je možné data získat (číst), metoda PATCH pak slouží pro update, apod.

Pro REST je také charakteristická bezestavovost. Tj. odpověď na každý požadavek představuje ucelenou informaci a nijak nezávisí na předchozích ani následujících požadavcích. Autentizace se provádí při každém požadavku. Uživatel je identifikován pomocí svého API klíče, který si lze vygenerovat v systému pro Advertisery (eHUB Advertiser Manager) nebo Publishery (eHUB publisher Manager). Tento klíč se pak přenáší v query parametru apiKey. Brzy přibude možnost přenášet klíč také v hlavičce požadavku.

Pro přenos dat používáme formát JSON. Zejména kvůli kompatibilitě se staršími systémy lze alternativně u některých endpointů zvolit pro formát odpovědi také XML.

Dokumentace je k dispozici na Apiary.io. API nese označení v3. Znamená to, že se jedná již o třetí verzi API afiliate sítě eHUB. Dosud však byly k dispozici pouze endpointy pro Advertisery. Verze 3 poprvé slouží také pro Publishery. Do konce roku budou postupně všechny endpointy z verze 2 po mírných úpravách a vylepšení převedeny do verze 3 a některé nové se ještě přidají. Následovat bude přechodové období, během kterého budou mít uživatelé čas na otestování a implementaci nového API. Potom dojde k definitivnímu odpojení všech předchozích verzí. V provozu zůstane pouze API verze 3, které bude sloužit jak pro Advertisery, tak pro Publishery.

A co se ještě chystá? Momentálně pracujeme na automatickém generátoru popisu API podle specifikace OpenAPI v3 (dříve Swagger). To nám mimo jiné umožní automaticky generovat dokumentaci, která tím výrazně získá na kvalitě. Zajištěna tím bude i aktuálnost za všech okolností, protože jakákoli změna v API se ihned promítne do dokumentace, aniž bychom se o to sami aktivně starali. Pomocí nástrojů Swagger si například také uživatelé budou moci velmi jednoduše vygenerovat klienta pro naše API. Na výběr je přitom více než dvacítka různých programovacích jazyků.