Jak verzujete REST API? rubrika: Programování: Jiné
9
Honza Břešťan
Narazil jsem na problem verzovani API a rad bych zjistil, jak verzujete vy a jestli k memu reseni mate nejake pripominky, klidne i literaturu, jak bych ho mohl vylepsit.
Predem podotykam, ze asi jedine mozne reseni je verzovat URI - data versioning pro me neni vhodny (je absolutni horor udrzovat si prehled, kde jaky field muze chybet nebo prebyvat a mit podle toho dokumentaci a kontrakty pro (de)serializer).
Nase REST sluzby jsou psane pomoci WCF; jsou to selfhosted WCF sluzby s endpointy zverejnene pres WebGetAttribute a WebInvokeAttribute. Pisu to proto, ze jsem neprisel na zpusob, jak mit vic URI zpracovanych jednou metodou. S WCF toho moc neudelam, ma svoje vyhody a nevyhody a je nad tim uz hotova infrastruktura. Otazka je ale nezavisla na jazyku a frameworku.
Dosavadni URI jsou hodne divoke, nekonzistentni, vetsinou to jsou slovesa/akce a ne resources. Postupne bych ale rad nasadil nasledujici format:
/Service/Resource/Version/?param={...} pro GET
/Service/Resource/Version/ plus postdata pro ostatni akce
Kamen urazu je v te verzi - v te WCF implementaci jsou jednotlive akce (GET, PUT...) routovany uplne nezavisle, takze by slo je i zvlast verzovat. Na jednu stranu mi to nedava smysl, protoze mi prijde lepsi verzovat cely resource, na druhou stranu ale WCF neumi (nebo jsem to neobjevil) k existujici metode pridat novou routu s vyssi verzi. Musel bych vytvorit novou metodu, ktera jen vola stejnou logiku. Nakonec jsem se rozhodl verzovat cely resource, ale jak to dava smysl vam?
Tim padem neumim jednoduse dosahnout stavu, kdy treba bude stejna logika a format GETu pro
/Service/Resource/ (vzdy by mela brat latest verzi API)
/Service/Resource/V2.1/ (explicitni latest verze)
/Service/Resource/V2/ (stejna logika a format jako pro V2.1, menila se nejaka jina akce)
Musel bych udrzovat hodne kodu, nezapominat presmerovavat tu implicitni verzi atd.
Muze tohle byt velky problem z pohledu (obecnych) API consumeru? Nebo idealne vite nekdo, jak tohle resit s WCF?
A jedna obecnejsi na zaver, jak verzujete na svych projektech a jake s tim mate zkusenosti?
8
Jakub Macek
Doporučoval bych zvážit, jestli se krokují verze jednotlivých zdrojů (resp. funkcí, které s nimi pracují), nebo je to celá služba, nebo dokonce celé API. První variantu bych považoval za chaos-generující, protože časem musí některé verze přejít do stavu nadbytečné a odstraněné - v takovém případě by bylo dost složité se v tom vyznat (bude funkční v3 a v4 pro GET a v2 pro POST). Pokud to cyklus vydání dovolí, doporučuji poslední variantu.
Potom je nejpřehlednějsí URL prefix (api.example.com/v1/service1/resource1/) nebo doménový prefix (v1.api.example.com/service1/resource1/). Samotné služby by pak byly adaptéry kolem logiky uvnitř, která už se může verzovat na úrovni funkcí.
Pro zobrazení všech 6 odpovědí se prosím přihlaste:
Nebo se přihlaste jménem a heslem:
Komentáře