這是有關(guān)使用Spring 3.1和Spring Security 3.1和基于Java的配置來建立安全的RESTful Web Service的系列文章的第四篇 。 本文將重點(diǎn)介紹REST API，HATEOAS的可發(fā)現(xiàn)性以及由測試驅(qū)動的實(shí)際方案。

引入REST可發(fā)現(xiàn)性

API的可發(fā)現(xiàn)性是一個值得引起足夠關(guān)注的主題，因此很少有API能夠正確地實(shí)現(xiàn)它。 如果做得正確，這也可以使API不僅具有RESTful和可用性，而且具有優(yōu)雅的風(fēng)格。

要了解可發(fā)現(xiàn)性 ，需要了解這種約束，即“超媒體作為應(yīng)用程序狀態(tài)引擎（HATEOAS）”； RESTful API的這種約束是關(guān)于作為應(yīng)用程序狀態(tài)唯一驅(qū)動程序的超媒體（實(shí)際上是超文本）對資源上的動作/轉(zhuǎn)換的完全可發(fā)現(xiàn)性。 如果交互作用是由API通過對話本身（特別是通過超文本）來驅(qū)動的，那么就沒有文檔 ，因?yàn)檫@會迫使客戶端做出實(shí)際上不在API上下文之外的假設(shè)。

此外，繼續(xù)這種邏輯思路，確實(shí)可以認(rèn)為RESTful API的唯一方法是，如果它可以從根完全發(fā)現(xiàn)并且沒有先驗(yàn)知識 ，這意味著客戶端應(yīng)該能夠通過在GET上進(jìn)行GET來導(dǎo)航API。根。 展望未來，所有狀態(tài)更改均由客戶端使用REST API在表示形式中提供的可用且可發(fā)現(xiàn)的轉(zhuǎn)換來驅(qū)動（因此稱為Representational State Transfer ）。

總之，服務(wù)器應(yīng)具有足夠的描述性，以指示客戶端如何僅通過超文本來使用API??，在HTTP對話的情況下，該超文本可能是Link標(biāo)頭。

具體的可發(fā)現(xiàn)性場景（由測試驅(qū)動）


那么，REST服務(wù)可被發(fā)現(xiàn)意味著什么？ 在本節(jié)中，我們將使用Junit， rest-assured和Hamcrest來測試可發(fā)現(xiàn)性的各個特征。 由于REST Service已在該系列的第3部分中得到保護(hù)，因此在使用API??之前，每個測試都需要首先進(jìn)行身份驗(yàn)證 。 還需要一些實(shí)用程序來解析響應(yīng)的Link標(biāo)頭。

發(fā)現(xiàn)有效的HTTP方法
當(dāng)使用無效的HTTP方法使用RESTful Web服務(wù)時，響應(yīng)應(yīng)為405 METHOD NOT ALLOWED ； 此外，它還應(yīng)該使用響應(yīng)中的“ 允許 HTTP標(biāo)頭”來幫助客戶端發(fā)現(xiàn)該特定資源所允許的有效HTTP方法：

@Test public void whenInvalidPOSTIsSentToValidURIOfResource_thenAllowHeaderListsTheAllowedActions(){// Givenfinal String uriOfExistingResource = this.restTemplate.createResource();// WhenResponse res = this.givenAuthenticated().post( uriOfExistingResource );// ThenString allowHeader = res.getHeader( HttpHeaders.ALLOW );assertThat( allowHeader, AnyOf.<String> anyOf( containsString("GET"), containsString("PUT"), containsString("DELETE") ) ); }

發(fā)現(xiàn)新創(chuàng)建的資源的URI
使用位置 HTTP標(biāo)頭，創(chuàng)建新資源的操作應(yīng)始終在響應(yīng)中包括新創(chuàng)建資源的URI。 如果客戶端在該URI上執(zhí)行GET，則該資源應(yīng)可用：

@Test public void whenResourceIsCreated_thenURIOfTheNewlyCreatedResourceIsDiscoverable(){// WhenFoo unpersistedResource = new Foo( randomAlphabetic( 6 ) );Response createResponse = this.givenAuthenticated().contentType( MIME_JSON ).body( unpersistedResource ).post( this.paths.getFooURL() );final String uriOfNewlyCreatedResource = createResp.getHeader( HttpHeaders.LOCATION );// ThenResponse response = this.givenAuthenticated().header( HttpHeaders.ACCEPT, MIME_JSON ).get( uriOfNewlyCreatedResource );Foo resourceFromServer = response.body().as( Foo.class );assertThat( unpersistedResource, equalTo( resourceFromServer ) ); }

該測試遵循一個簡單的場景：創(chuàng)建一個新的Foo資源，并使用HTTP響應(yīng)來發(fā)現(xiàn)該資源現(xiàn)在可訪問的URI 。 然后，測試會更進(jìn)一步，并對該URI進(jìn)行GET檢索以獲取資源并將其與原始資源進(jìn)行比較，以確保資源已正確保留。

發(fā)現(xiàn)URI以獲取該類型的所有資源
當(dāng)我們獲取特定的Foo實(shí)例時，我們應(yīng)該能夠發(fā)現(xiàn)下一步可以做什么：我們可以列出所有可用的Foo資源。 因此，獲取資源的操作應(yīng)始終在其響應(yīng)中包含URI，以在何處獲取該類型的所有資源，再次使用Link標(biāo)頭：

@Test public void whenResourceIsRetrieved_thenURIToGetAllResourcesIsDiscoverable(){// GivenString uriOfExistingResource = this.restTemplate.createResource();// WhenResponse getResponse = this.givenAuthenticated().get( uriOfExistingResource );// ThenString uriToAllResources = HTTPLinkHeaderUtils.extractURIByRel( getResponse.getHeader( "Link" ), "collection" );Response getAllResponse = this.givenAuthenticated().get( uriToAllResources );assertThat( getAllResponse.getStatusCode(), is( 200 ) ); }

該測試解決了REST中鏈接關(guān)系的一個棘手問題：要檢索所有資源的URI使用rel =“ collection”語義。 這種類型的鏈接關(guān)系尚未標(biāo)準(zhǔn)化，但已被多種微格式使用 ，并已提出標(biāo)準(zhǔn)化要求。 非標(biāo)準(zhǔn)鏈接關(guān)系的使用打開了有關(guān)RESTful Web服務(wù)中的微格式和更豐富語義的討論。

其他可能發(fā)現(xiàn)的URI和微格式

其他URI可能會通過Link標(biāo)頭發(fā)現(xiàn)，但是在沒有轉(zhuǎn)移到更豐富的語義標(biāo)記（例如定義 自定義鏈接關(guān)系 ， Atom發(fā)布協(xié)議或微格式）的情況下 ，現(xiàn)有的鏈接關(guān)系類型只有這么多。另一篇文章。

例如，如果在特定資源上執(zhí)行GET時客戶端可以發(fā)現(xiàn)URI來創(chuàng)建新資源，那將是一個很好的選擇。 不幸的是，與模型創(chuàng)建語義沒有鏈接關(guān)系。 幸運(yùn)的是，標(biāo)準(zhǔn)做法是創(chuàng)建的URI與獲取該類型的所有資源的URI相同，唯一的區(qū)別是POST HTTP方法。

結(jié)論

本文介紹了RESTful Web服務(wù)上下文中可發(fā)現(xiàn)性的一些特征，討論了HTTP方法發(fā)現(xiàn)，創(chuàng)建和獲取之間的關(guān)系，發(fā)現(xiàn)URI以獲取所有資源的關(guān)系等。在接下來的文章中，我將重點(diǎn)介紹從root ，分頁，自定義鏈接關(guān)系，Atom發(fā)布協(xié)議以及Spring REST服務(wù)中的Discoverability的實(shí)際實(shí)現(xiàn)開始發(fā)現(xiàn)API。 同時，檢查github項目 。

參考： RESTful Web服務(wù)可發(fā)現(xiàn)性，我們的JCG合作伙伴 Eugen Paraschiv在baeldung博客上的第4部分 。

相關(guān)文章 ：

• 使用Spring 3.1和基于Java的配置引導(dǎo)Web應(yīng)用程序，第1部分
• 使用Spring 3.1和基于Java的配置構(gòu)建RESTful Web服務(wù)，第2部分
• 使用Spring Security 3.1保護(hù)RESTful Web服務(wù)，第3部分
• Spring的REST服務(wù)發(fā)現(xiàn)性，第5部分
• 使用Spring Security 3.1的RESTful服務(wù)進(jìn)行基本身份驗(yàn)證和摘要身份驗(yàn)證，第6部分
• Spring＆Quartz集成自定義注釋
• Spring MVC攔截器示例
• 在運(yùn)行時交換出Spring Bean配置

翻譯自: https://www.javacodegeeks.com/2011/12/restful-web-service-discoverability.html

總結(jié)

以上是生活随笔為你收集整理的RESTful Web服务可发现性，第4部分的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。