目次

タイプ]

link:#microformats[

4. ** その他の潜在的な発見可能なURIと

マイクロフォーマット]




5. ** まとめ


1概要

この記事では、

REST APIの発見可能性、HATEOAS

、およびテストによって推進される実用的なシナリオに焦点を当てます。


2 APIを発見可能にする理由

APIの

発見可能性

は十分にふさわしい注目を集めることができないトピックであり、結果として非常に少数のAPIがそれを正しくします。また、正しく行われた場合、APIがRESTfulで使用可能になるだけでなく、洗練されたものになることもあります。

  • 発見可能性

    を理解するには、その制約がアプリケーション状態のエンジンとしてのハイパーメディア(HATEOAS)であることを理解する必要があります。 REST APIのこの制約は、http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-として、ハイパーメディア(実際にはハイパーテキスト)からリソース上のアクション/遷移の完全な発見可能性についてです。アプリケーション状態の[

    only driver ** ]駆動。

対話自体が会話自体を通じて、具体的にはハイパーテキストを介してAPIによって

駆動

される場合、

ドキュメント

が存在しない可能性があります。

結論として、** サーバは、ハイパーテキストのみを介してAPIを使用する方法をクライアントに指示するのに十分なほど記述的である必要があります。これは、HTTP会話の場合は

Link

ヘッダになります。


3発見可能性シナリオ(テストによる)

それでは、RESTサービスが

発見可能

であることはどういう意味ですか?このセクションでは、Junit、http://code.google.com/p/rest-assured/[rest-assured]、およびhttp://code.google.com/p/hamcrest/を使用して、個々の発見可能性をテストします。[ハムクレスト]

RESTサービスは以前にセキュリティ保護されています

ので、各テストは消費する前にまずhttps://gist.github.com/1341570[認証]する必要がありますAPI


3.1. 有効なHTTPメソッドを発見する

RESTサービスが

無効なHTTPメソッド

で消費された場合、応答は

405 METHOD NOT ALLOWED

になります。加えて、それはまた、応答に


Allow


HTTP Headerを使用して、その特定のリソースに対して許可されている有効なHTTPメソッドを

発見

するのを手助けするべきです。

@Test
public void
 whenInvalidPOSTIsSentToValidURIOfResource__thenAllowHeaderListsTheAllowedActions(){
  //Given
   String uriOfExistingResource = restTemplate.createResource();

  //When
   Response res = givenAuth().post( uriOfExistingResource );

  //Then
   String allowHeader = res.getHeader( HttpHeaders.ALLOW );
   assertThat( allowHeader, AnyOf.<String> anyOf(
    containsString("GET"), containsString("PUT"), containsString("DELETE") ) );
}


3.2. 新しく作成されたリソースのURIを知る

新しいリソースを作成する操作は、


Location


HTTPヘッダーを使用して、常に新しく作成されたリソースのURIを応答に含める必要があります。クライアントがそのURIに対してGETを実行すると、リソースが利用可能になります。

@Test
public void whenResourceIsCreated__thenUriOfTheNewlyCreatedResourceIsDiscoverable() {
   //When
    Foo newResource = new Foo(randomAlphabetic(6));
    Response createResp = givenAuth().contentType("application/json")
      .body(unpersistedResource).post(getFooURL());
    String uriOfNewResource= createResp.getHeader(HttpHeaders.LOCATION);

   //Then
    Response response = givenAuth().header(HttpHeaders.ACCEPT, "application/json")
      .get(uriOfNewResource);

    Foo resourceFromServer = response.body().as(Foo.class);
    assertThat(newResource, equalTo(resourceFromServer));
}

このテストは単純なシナリオに従います。新しい

Foo

リソースが作成され、HTTP応答を使用して、リソースにアクセスできるようになった場所のURIを

発見します

。次にテストはさらに一歩進み、そのURIに対してGETを実行してリソースを取得し、それを元のリソースと比較して、リソースが正しく永続化されていることを確認します。

** 3.3. そのタイプのすべてのリソースをGETするためのURIを発見する

特定の

Foo

リソースを取得すると、次にできることを

発見

できるようになります。利用可能なすべての

Foo

リソースを一覧表示できます。したがって、リソースを取得する操作では、その応答に常にそのタイプのすべてのリソースを取得する場所のURIを含める必要があります。ここでも


Link


ヘッダーを使用します。

@Test
public void whenResourceIsRetrieved__thenUriToGetAllResourcesIsDiscoverable() {
   //Given
    String uriOfExistingResource = createAsUri();

   //When
    Response getResponse = givenAuth().get(uriOfExistingResource);

   //Then
    String uriToAllResources = HTTPLinkHeaderUtil
      .extractURIByRel(getResponse.getHeader("Link"), "collection");

    Response getAllResponse = givenAuth().get(uriToAllResources);
    assertThat(getAllResponse.getStatusCode(), is(200));
}


extractURIByRel

の完全な低レベルのコード –

rel

の関係によってURIを抽出する責任があることに注意してください。

このテストはRESTにおける** Link Relationsの厄介な問題をカバーしています。

このタイプのリンク関係はまだ標準化されていませんが、すでにいくつかのマイクロフォーマットによってhttp://microformats.org/wiki/existing-rel-values#non

HTML

rel__values[使用中]であり、標準化のために提案されています。非標準のリンク関係を使用すると、RESTful Webサービスのマイクロフォーマットと豊富なセマンティクスに関する議論が始まります。


4その他の発見可能なURIおよびマイクロフォーマット

他のURIは


Link


ヘッダを介して発見される可能性がありますが、http://tools.ietf.org/html/rfc5988#sectionのようなより豊富なセマンティックマークアップに移行せずに許可されている既存のタイプのリンク関係だけが可能です-6.2.1[カスタムリンク関係の定義]、http://tools.ietf.org/html/rfc5023[Atom Publishing Protocol]またはhttp://en.wikipedia.org/wiki/Microformat[microformats]別の記事のトピックになります。

たとえば、クライアントは、特定のリソースに対して

GET

を実行するときに、

新しいリソースを作成するためのURIを

発見できるはずです。残念ながら、model

create

semanticsへのリンク関係はありません。幸いなことに、作成のためのURIはそのタイプのすべてのリソースをGETするためのURIと同じですが、唯一の違いはPOST HTTPメソッドです。これを実現するためにフォームを使用することもできます。


5結論

REST APIがどのようにして

ルートから

および

事前知識なし

に完全に発見可能であるか – クライアントがルート上でGETを実行することによってそれをナビゲートできることを意味します。先に進むと、すべての状態変更はREST APIが表現で提供する利用可能で発見可能な遷移を使用してクライアントによって実行されます(したがって

Representational State Transfer

)。

この記事では、REST Webサービスのコンテキストにおける発見可能性のいくつかの特性について説明し、HTTPメソッドの発見、createとgetの関係、すべてのリソースを入手するためのURIの発見などについて説明しました。

これらすべての例とコードスニペットの実装は


my GitHub project


にあります。そのため、インポートしてそのまま実行するのは簡単なはずです。