Viditeľnosť rozhrania REST API a HATEOAS
Práve som oznámil nové Naučte sa jar kurz zameraný na základy jari 5 a Spring Boot 2:
>> SKONTROLUJTE KURZ1. Prehľad
Tento článok sa zameria na Viditeľnosť rozhrania REST API, HATEOAS a praktické scenáre vychádzajúce z testov.
2. Prečo urobiť API viditeľným
Viditeľnosť API je téma, ktorej sa nedostáva dostatok zaslúženej pozornosti. Dôsledkom toho je veľmi málo API, ktoré to napravia. Je to tiež niečo, čo, ak sa vykoná správne, môže spôsobiť, že API bude nielen RESTful a použiteľné, ale aj elegantné.
Aby sme pochopili objaviteľnosť, musíme pochopiť obmedzenie Hypermedia As The Engine Of Application State (HATEOAS). Toto obmedzenie rozhrania REST API sa týka úplnej objaviteľnosti akcií / prechodov na zdroji z Hypermedie (skutočne Hypertext), ako jediného ovládača stavu aplikácie.
Ak má byť interakcia riadená API prostredníctvom samotnej konverzácie, konkrétne prostredníctvom Hypertextu, potom nemusí byť k dispozícii žiadna dokumentácia. To by klienta prinútilo urobiť predpoklady, ktoré sú v skutočnosti mimo kontextu API.
Na záver, server by mal byť dostatočne popisný, aby klienta poučil, ako používať API iba cez Hypertext. V prípade konverzácie cez HTTP by sme to mohli dosiahnuť prostredníctvom Odkaz hlavička.
3. Scenáre objaviteľnosti (riadené testami)
Čo to znamená, aby bola služba REST viditeľná?
V tejto časti budeme testovať jednotlivé črty objaviteľnosti pomocou programu Junit, zaisteného odpočinku a Hamcrestu. Keďže služba REST bola predtým zabezpečená, pred použitím API je potrebné najskôr autentifikovať každý test.
3.1. Objavte platné metódy HTTP
Keď sa služba REST spotrebuje pomocou neplatnej metódy HTTP, odpoveď by mala byť 405 METÓDA NIE JE POVOLENÁ.
Rozhranie API by malo tiež pomôcť klientovi nájsť platné metódy HTTP, ktoré sú pre daný konkrétny zdroj povolené. Pre to, môžeme použiť Povoliť Hlavička HTTP v odpovedi:
@Test public void whenInvalidPOSTIsSentToValidURIOfResource_thenAllowHeaderListsTheAllowedActions () {// Daný reťazec uriOfExistingResource = restTemplate.createResource (); // When Response res = givenAuth (). Post (uriOfExistingResource); // Potom String allowHeader = res.getHeader (HttpHeaders.ALLOW); assertThat (allowHeader, AnyOf.anyOf (containsString ("GET"), containsString ("PUT"), containsString ("DELETE"))); }3.2. Objavte URI novovytvoreného zdroja
Operácia vytvorenia nového zdroja by mala vždy zahrnúť do odpovede URI novovytvoreného zdroja. Na tento účel môžeme použiť Poloha Hlavička HTTP.
Teraz, ak klient urobí GET na tomto URI, zdroj by mal byť k dispozícii:
@Test public void whenResourceIsCreated_thenUriOfTheNewlyCreatedResourceIsDiscoverable () {// When Foo newResource = new Foo (randomAlphabetic (6)); Odozva createResp = givenAuth (). ContentType ("application / json") .body (unpersistedResource) .post (getFooURL ()); Reťazec uriOfNewResource = createResp.getHeader (HttpHeaders.LOCATION); // Potom Response response = givenAuth (). Header (HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE) .get (uriOfNewResource); Foo resourceFromServer = response.body (). As (Foo.class); assertThat (newResource, equalTo (resourceFromServer)); }Test sleduje jednoduchý scenár: vytvorenie nového Foo prostriedku a potom pomocou odpovede HTTP vyhľadať URI, kde je teraz zdroj k dispozícii. Potom tiež urobí GET na tomto URI, aby získal zdroj a porovná ho s originálom. Týmto sa uistíte, že bolo správne uložené.
3.3. Objavte identifikátor URI a ZÍSKAJTE všetky zdroje tohto typu
Keď ZÍSKAME nejaké konkrétne Foo zdroje, mali by sme byť schopní zistiť, čo môžeme urobiť ďalej: môžeme uviesť zoznam všetkých dostupných Foo zdrojov. Operácia načítania zdroja by teda mala vždy obsahovať vo svojej odpovedi URI, kde je možné získať všetky zdroje tohto typu.
Na tento účel môžeme opäť použiť Odkaz hlavička:
@Test public void whenResourceIsRetrieved_thenUriToGetAllResourcesIsDiscoverable () {// Daný reťazec uriOfExistingResource = createAsUri (); // When Response getResponse = givenAuth (). Get (uriOfExistingResource); // Potom String uriToAllResources = HTTPLinkHeaderUtil .extractURIByRel (getResponse.getHeader ("Odkaz"), "zbierka"); Odpoveď getAllResponse = givenAuth (). Get (uriToAllResources); assertThat (getAllResponse.getStatusCode (), je (200)); }Upozorňujeme, že celý nízkoúrovňový kód pre extraktURIByRel - zodpovedný za extrakciu URI do rel tu je zobrazený vzťah.
Tento test sa zaoberá tŕnistým predmetom Link Relations v REST: identifikátor URI na získanie všetkých zdrojov používa rel = ”zbierka” sémantika.
Tento typ väzbového vzťahu ešte nebol štandardizovaný, ale už ho používa niekoľko mikroformátov a navrhuje sa na štandardizáciu. Použitie neštandardných vzťahov odkazov otvára diskusiu o mikroformátoch a bohatšej sémantike vo webových službách RESTful.
4. Ďalšie potenciálne objaviteľné URI a mikroformáty
Ďalšie identifikátory URI by sa dali potenciálne nájsť prostredníctvom servera Odkaz hlavička, ale existuje len toľko, čo umožňujú existujúce typy vzťahov odkazov bez toho, aby sme prešli na bohatšie sémantické značky, ako je definovanie vlastných vzťahov odkazov, Atom Publishing Protocol alebo mikroformáty, ktoré budú témou iného článku.
Napríklad, klient by mal byť schopný zistiť URI na vytvorenie nových zdrojov, keď robí ZÍSKAJTE na konkrétny zdroj. Bohužiaľ neexistuje žiadny vzťah k modelu vytvoriť sémantika.
Našťastie je štandardnou praxou, že identifikátor URI na vytvorenie je rovnaký ako identifikátor URI a ZÍSKAVA všetky zdroje tohto typu, pričom jediným rozdielom je metóda POST HTTP.
5. Záver
Videli sme ako je REST API plne odhaliteľné z koreňového adresára a bez predchádzajúcich znalostí - čo znamená, že klient je schopný sa v ňom pohybovať pomocou funkcie GET v koreňovom adresári. Vpred sú všetky zmeny stavu riadené klientom pomocou dostupných a objaviteľných prechodov, ktoré poskytuje REST API v reprezentáciách (teda Transfer reprezentačného štátu).
Tento článok sa venoval niektorým črtám objaviteľnosti v kontexte webovej služby REST, pojednáva o objavovaní metód HTTP, vzťahu medzi vytváraním a získavaním, objavovaní URI na získanie všetkých zdrojov atď.
Implementácia všetkých týchto príkladov a útržkov kódu je k dispozícii na stránkach GitHub. Toto je projekt založený na Maven, takže by malo byť ľahké ho importovať a spustiť tak, ako je.
REST spodok
