streamalism.org

Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak:

1. Áttekintés

Ez a cikk a következőkre fog összpontosítani A REST API, a HATEOAS felfedezhetősége tesztek által vezérelt gyakorlati forgatókönyvek.

2. Miért tegye elérhetővé az API-t?

Az API felfedezhetősége olyan téma, amely nem kap elég jól megérdemelt figyelmet. Ennek következtében nagyon kevés API érti el helyesen. Ez egy olyan dolog is, amely helyesen végrehajtva az API-t nemcsak RESTful és használhatóvá, hanem elegánssá is teheti.

A felfedezhetõség megértéséhez meg kell értenünk a Hypermedia mint az alkalmazás állapotának (HATEOAS) korlátját. A REST API ezen korlátozása a műveletek / átmenetek teljes felismerhetőségéről szól a Hypermedia erőforrásán (a Hypertext valójában), mint az alkalmazás állapotának egyetlen meghajtóján.

Ha az interakciót az API vezérli a beszélgetésen keresztül, konkrétan a Hypertext segítségével, akkor nem lehet dokumentáció. Ez arra kényszerítené az ügyfelet, hogy olyan feltételezéseket tegyen, amelyek valójában kívül esnek az API kontextusán.

Következtetésképpen, a szervernek elég leírónak kell lennie ahhoz, hogy utasítsa az ügyfelet az API használatáról csak a Hypertext segítségével. HTTP beszélgetés esetén ezt a Link fejléc.

3. Felfedezhetőségi forgatókönyvek (tesztek vezérlik)

Tehát mit jelent a REST szolgáltatás felfedezhetősége?

Ebben a szakaszban a felfedezhetőség egyes vonásait teszteljük a Junit, a nyugodt és a Hamcrest segítségével. Mivel a REST szolgáltatás már korábban biztosított, minden tesztnek először hitelesítenie kell magát az API használata előtt.

3.1. Fedezze fel az Érvényes HTTP módszereket

Ha egy REST szolgáltatást érvénytelen HTTP módszerrel fogyasztanak, akkor a válasznak 405 MÓDSZER NEM Engedélyezettnek kell lennie.

Az API-nak segítenie kell az ügyfelet az adott erőforrás számára engedélyezett érvényes HTTP-módszerek felderítésében is. Ezért, használhatjuk a Lehetővé teszi HTTP fejléc a válaszban:

@Test public void whenInvalidPOSTIsSentToValidURIOfResource_thenAllowHeaderListsTheAllowedActions () {// Adott karakterlánc uriOfExistingResource = restTemplate.createResource (); // Amikor a válasz res = megadottAuth (). Post (uriOfExistingResource); // Ezután String allowHeader = res.getHeader (HttpHeaders.ALLOW); assertThat (allowHeader, AnyOf.anyOf (tartalmazString ("GET"), tartalmazzaString ("PUT"), tartalmazzaString ("TÖRLÉS"))); }

3.2. Fedezze fel az újonnan létrehozott erőforrás URI-ját

Az új erőforrás létrehozásának mindig tartalmaznia kell az újonnan létrehozott erőforrás URI-ját a válaszban. Ehhez használhatjuk a Elhelyezkedés HTTP fejléc.

Most, ha az ügyfél GET-et hajt végre az adott URI-n, az erőforrásnak elérhetőnek kell lennie:

@Test public void whenResourceIsCreated_thenUriOfTheNewlyCreatedResourceIsDiscoverable () {// When Foo newResource = new Foo (randomAlphabetic (6)); Válasz createResp = givenAuth (). ContentType ("application / json") .body (unpersistedResource) .post (getFooURL ()); Karakterlánc uriOfNewResource = createResp.getHeader (HttpHeaders.LOCATION); // Ezután Válaszválasz = megadottAuth (). Fejléc (HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE) .get (uriOfNewResource); Foo resourceFromServer = response.body (). As (Foo.osztály); assertThat (newResource, equTo (resourceFromServer)); }

A teszt egyszerű forgatókönyvet követ: új létrehozása Foo erőforrást, majd a HTTP válasz segítségével fedezze fel az URI-t, ahol az erőforrás már elérhető. Ezután GET-t is végez az adott URI-n az erőforrás lekérése és az eredetihez való összehasonlítása céljából. Ennek célja, hogy megbizonyosodjon a megfelelő mentésről.

3.3. Fedezze fel az URI-t az összes ilyen típusú erőforrás beszerzéséhez

Amikor valamilyen különlegeset kapunk Foo erőforrást, meg kell tudnunk fedezni, hogy mit tehetünk ezután: felsorolhatjuk az összes elérhetőt Foo erőforrások. Így az erőforrás visszakeresésének műveletének mindig válaszában fel kell tüntetnie az URI-t, hogy hol szerezze be az összes ilyen típusú erőforrást.

Ehhez ismét felhasználhatjuk a Link fejléc:

@Test public void whenResourceIsRetrieved_thenUriToGetAllResourcesIsDiscoverable () {// Adott karakterlánc uriOfExistingResource = createAsUri (); // Amikor a válasz getResponse = adottAuth (). Get (uriOfExistingResource); // Ezután String uriToAllResources = HTTPLinkHeaderUtil .extractURIByRel (getResponse.getHeader ("Link"), "gyűjtemény"); Válasz getAllResponse = megadottAuth (). Get (uriToAllResources); assertThat (getAllResponse.getStatusCode (), (200)); }

Vegye figyelembe, hogy a (z) teljes alacsony szintű kódja extractURIByRel - felelős az URI-k kibontásáért rel reláció látható itt.

Ez a teszt a REL linkkapcsolatok tövises témáját fedi le: az összes erőforrás lekérésére szolgáló URI a rel = ”gyűjtemény” szemantika.

Az ilyen típusú kapcsolatkapcsolatot még nem szabványosították, de már számos mikroformátum használja, és javasolta a szabványosításra. A nem szabványos kapcsolatok használata megnyitja a vitát a RESTful webszolgáltatások mikroformátumairól és gazdagabb szemantikájáról.

4. Egyéb lehetséges felfedezhető URI-k és mikroformátumok

Más URI-k potenciálisan felfedezhetők a Link fejléc, de csak annyit engednek meg a meglévő linkkapcsolatok, hogy egy gazdagabb szemantikai jelölésig elmozdulnánk, mint például az egyéni linkkapcsolatok meghatározása, az Atom Publishing Protocol vagy a mikroformátumok, amelyek egy másik cikk témája lesznek.

Például az ügyfélnek képesnek kell lennie felfedezni az URI-t új erőforrások létrehozásához, amikor a KAP egy adott erőforráson. Sajnos nincs kapcsolat a modellel teremt szemantika.

Szerencsére ez a szokásos gyakorlat, hogy a létrehozáshoz szükséges URI megegyezik az URI-val az összes ilyen típusú erőforrás megszerzéséhez, az egyetlen különbség a POST HTTP módszer.

5. Következtetés

Láttuk hogy a REST API hogyan lehet teljes mértékben felfedezhető a gyökérből és előzetes ismeretek nélkül - vagyis az ügyfél képes navigálni abban, hogy GET-t csinál a gyökéren. Tovább haladva az összes állapotváltozást az ügyfél vezérli a rendelkezésre álló és felfedezhető átmenetekkel, amelyeket a REST API reprezentációkban nyújt (tehát Reprezentatív állami kimutatás).

Ez a cikk a REST webszolgáltatás összefüggésében fedezte fel a felfedezhetőség néhány jellemzőjét, a HTTP módszer felfedezéséről, a létrehozás és megszerzés kapcsolatáról, az összes erőforrás megszerzéséhez szükséges URI felfedezéséről stb.

Ezeknek a példáknak és kódrészleteknek a megvalósítása elérhető a GitHubon. Ez egy Maven-alapú projekt, ezért könnyen importálhatónak és futtathatónak kell lennie.

Most jelentettem be az újat Tanulj tavaszt tanfolyam, amelynek középpontjában az 5. tavasz és a tavaszi bakancs 2 alapjai állnak: