restful web_RESTful Web服务可发现性，第4部分

restful web

这是关于使用Spring 3.1和Spring Security 3.1和基于Java的配置来建立安全的RESTful Web Service的系列文章的第四篇 。本文将重点介绍REST API，HATEOAS的可发现性以及由测试驱动的实际方案。

引入REST可发现性

API的可发现性是一个值得引起足够关注的主题，因此很少有API能够正确地实现它。如果做得正确，这也可以使API不仅具有RESTful和可用性，而且具有优雅的风格。

要了解可发现性 ，需要了解这种约束，即作为应用程序状态引擎（HATEOAS）的超媒体。 RESTful API的这种约束是关于作为应用程序状态唯一驱动程序的超媒体（实际上是超文本）对资源上的动作/转换的完全可发现性。如果交互作用是由API通过对话本身（特别是通过超文本）来驱动的，那么就不可能有文档，因为这会迫使客户端做出实际上不在API上下文之外的假设。

此外，继续这种逻辑思路，确实可以认为RESTful API的唯一方法是，如果从根完全可以发现它并且没有先验知识 ，这意味着客户端应该能够通过在GET上执行GET来导航API。根。展望未来，所有状态更改均由客户端使用REST API在表示形式中提供的可用且可发现的转换来驱动（因此称为Representational State Transfer ）。

总之，服务器应具有足够的描述性，以指示客户端如何仅通过超文本来使用API，在HTTP对话的情况下，它可能是Link标头。

具体的可发现性场景（由测试驱动）

那么，REST服务可被发现意味着什么？在本节中，我们将使用Junit， rest-assured和Hamcrest来测试可发现性的各个特征。由于REST Service已在该系列的第3部分中得到保护，因此在使用API之前，每个测试都需要首先进行身份验证。还需要一些实用程序来解析响应的Link标头。

发现有效的HTTP方法
当使用无效的HTTP方法使用RESTful Web服务时，响应应为405 METHOD NOT ALLOWED ；此外，它还应该使用响应中的“ 允许 HTTP标头”来帮助客户端发现该特定资源所允许的有效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") ) );
}

发现新创建的资源的URI
使用位置 HTTP标头，创建新资源的操作应始终在响应中包括新创建资源的URI。如果客户端在该URI上执行GET，则该资源应可用：

@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 ) );
}

该测试遵循一个简单的场景：创建一个新的Foo资源，并使用HTTP响应来发现该资源现在可访问的URI 。然后，测试会更进一步，并对该URI进行GET检索以获取资源并将其与原始资源进行比较，以确保资源已正确保留。

发现URI以获取该类型的所有资源
当我们获取特定的Foo实例时，我们应该能够发现下一步可以做什么：我们可以列出所有可用的Foo资源。因此，检索资源的操作应始终在其响应中包含URI，以在何处获取该类型的所有资源，再次使用Link标头：

@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中链接关系的一个棘手问题：要检索所有资源的URI使用rel =“ collection”语义。这种类型的链接关系尚未标准化，但已被多种微格式使用，并已提出标准化要求。非标准链接关系的使用开启了有关RESTful Web服务中的微格式和更丰富语义的讨论。

其他可能发现的URI和微格式

其他URI可能会通过Link标头发现，但是在没有转移到更丰富的语义标记（例如定义自定义链接关系， Atom发布协议或微格式）的情况下，现有的链接关系类型只有这么多。另一篇文章。

例如，如果在特定资源上执行GET时客户端可以发现URI来创建新资源，那将是一个很好的选择。不幸的是，与模型创建语义没有链接关系。幸运的是，标准做法是，用于创建的URI与用于获取该类型所有资源的URI相同，唯一的区别是POST HTTP方法。

结论

本文介绍了RESTful Web服务上下文中可发现性的一些特征，讨论了HTTP方法发现，创建与获取之间的关系，发现URI以获取所有资源的关系等。在接下来的文章中，我将重点介绍从root ，分页，自定义链接关系，Atom发布协议以及Spring REST服务中的Discoverability的实际实现开始发现API。同时，检查github项目。

参考： RESTful Web Service可发现性，我们的JCG合作伙伴 Eugen Paraschiv在baeldung博客上的第4部分。

相关文章：