Spring RESTとHALブラウザ

Spring RESTおよびHALブラウザー

1. 概要

このチュートリアルでは、what HAL is and why it’s useful, before introducing the HAL browserについて説明します。

次に、Springを使用して、いくつかの興味深いエンドポイントを含む単純なREST APIを構築し、データベースにいくつかのテストデータを入力します。

最後に、HALブラウザーを使用して、REST APIを調べ、そこに含まれるデータをトラバースする方法を見つけます。

2. HALおよびHALブラウザー

JSON Hypertext Application Language、またはHALは、gives a consistent and easy way to hyperlink between resources in our APIという単純な形式です。 REST APIにHALを含めると、本質的に自己文書化されるだけでなく、ユーザーにとってもはるかに探索しやすくなります。

APIに関連する情報の概要を示すデータをJSON形式で返すことで機能します。

HAL model revolves around two simple concepts.

以下を含むResources,：

関連するURIへのリンク
組み込みリソース
状態

リンク集

ターゲットURI
リンクとの関係、またはrel
減価償却、コンテンツネゴシエーションなどに役立つ他のいくつかのオプションプロパティ

HALブラウザは、HALとprovides an in-browser GUI to traverse your REST APIを開発したのと同じ人によって作成されました。

次に、簡単なREST APIを作成し、HALブラウザーをプラグインして、機能を調べます。

3. 依存関係

以下は、HALブラウザーをREST APIに統合するために必要な単一の依存関係です。 APIの残りの依存関係は、GitHub codeにあります。

まず、Mavenベースのプロジェクトのthe dependency：


    org.springframework.data
    spring-data-rest-hal-browser
    3.0.8.RELEASE

Gradleを使用してビルドしている場合は、次の行をbuild.gradle fileに追加できます。

compile group: 'org.springframework.data', name: 'spring-data-rest-hal-browser', version: '3.0.8.RELEASE'

4. シンプルなREST APIの構築

4.1. シンプルなデータモデル

この例では、ライブラリ内のさまざまな本を閲覧するための単純なRESTAPIを設定します。

ここで、Hibernateでデータを永続化できるように、適切な注釈を含む簡単な本エンティティを定義します。

@Entity
public class Book {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private long id;

  @NotNull
  @Column(columnDefinition = "VARCHAR", length = 100)
  private String title;

  @NotNull
  @Column(columnDefinition = "VARCHAR", length = 100)
  private String author;

  @Column(columnDefinition = "VARCHAR", length = 1000)
  private String blurb;

  private int pages;

  // usual getters, setters and constructors

}

4.2. CRUDリポジトリの紹介

次に、いくつかのエンドポイントが必要になります。これを行うには、leverage the *PagingAndSortingRepository* を使用して、Book センティティからデータを取得するように指定します。

このクラスprovides simple CRUD commands, as well as paging and sorting capabilitiesは、箱から出してすぐに使用できます。

@Repository
public interface BookRepository extends PagingAndSortingRepository {

    @RestResource(rel = "title-contains", path="title-contains")
    Page findByTitleContaining(@Param("query") String query, Pageable page);

    @RestResource(rel = "author-contains", path="author-contains", exported = false)
    Page findByAuthorContaining(@Param("query") String query, Pageable page);
}

これが少し奇妙に見える場合、またはSpringリポジトリについて詳しく知りたい場合は、hereをもっと読むことができます。

2つの新しいエンドポイントを追加して、リポジトリを拡張しました。

findByTitleContaining – は、タイトルに含まれるクエリを含む書籍を返します
findByAuthorContaining –は、本の著者にクエリが含まれているデータベースから本を返します

second endpoint contains the export = false attributeに注意してください。この属性はstops the HAL links being generated for this endpointであり、HALブラウザからは使用できません。

最後に、Springの起動時に、ApplicationRunnerインターフェースを実装するクラスを定義してデータを読み込みます。コードはGitHubにあります。

5. HALブラウザーのインストール

HALブラウザのセットアップは、SpringでREST APIを構築する際に非常に簡単です。依存関係がある限り、Springはブラウザを自動設定し、デフォルトのエンドポイントを介してブラウザを利用可能にします。

ここで必要なのは、実行ボタンを押してブラウザに切り替えることだけです。その後、HALブラウザはhttp://localhost:8080/で利用できるようになります

6. HALブラウザーを使用したREST APIの調査

HAL browser is broken down into two parts – the explorer and the inspector。各セクションを個別に分析して説明します。

6.1. HAL Explorer

聞こえるように、エクスプローラーはexploring new parts of our API relative to the current endpointに専念しています。検索バーと、現在のエンドポイントのCustom Request Headers and Propertiesを表示するテキストボックスが含まれています。

これらの下に、リンクセクションと埋め込みリソースのクリック可能なリストがあります。

6.2. リンクを使用する

/books endpointに移動すると、既存のリンクを表示できます。

隣接するセクションのこれらのlinks are generated from the HAL：

"_links": {
    "first": {
      "href": "http://localhost:8080/books?page=0&size=20"
    },
    "self": {
      "href": "http://localhost:8080/books{?page,size,sort}",
      "templated": true
    },
    "next": {
      "href": "http://localhost:8080/books?page=1&size=20"
    },
    "last": {
      "href": "http://localhost:8080/books?page=4&size=20"
    },
    "profile": {
      "href": "http://localhost:8080/profile/books"
    },
    "search": {
      "href": "http://localhost:8080/books/search"
    }
  },

検索エンドポイントに移動すると、PagingAndSortingRepository:を使用して作成したカスタムエンドポイントを表示することもできます

{
  "_links": {
    "title-contains": {
      "href": "http://localhost:8080/books/search/title-contains{?query,page,size,sort}",
      "templated": true
    },
    "self": {
      "href": "http://localhost:8080/books/search"
    }
  }
}

上記のHALは、title-contains endpoint displaying suitable search criteria.を示しています。エクスポートしないように定義したため、author-containsエンドポイントが欠落していることに注意してください。

6.3. 埋め込みリソースの表示

埋め込みリソースには、/booksエンドポイントのdetails of the individual book recordsが表示されます。各リソースには、独自のProperties およびLinks sectionも含まれています。

6.4. フォームを使用する

リンクセクション内の[GET]列の[疑問符]ボタンは、フォームモーダルを使用してカスタム検索条件を入力できることを示します。

title-contains endpointのフォームは次のとおりです。

The HAL browser selection form

カスタムURIはfirst page of 20 books where the title contains the word ‘Java'.を返します

6.5. Halインスペクター

インスペクターはブラウザーの右側を構成し、チュートリアルの前半で見たResponse Headers and Response Body. ThisHAL data is used to render the Links and Embedded Resources を含みます。

7. 結論

この記事では、HALとは何か、なぜそれが役立つのか、そしてなぜそれがsuperior self-documenting REST APIs.の作成に役立つのかを要約しました。

Springを使用してPagingAndSortingRepositoryを実装するシンプルなREST APIを構築し、独自のエンドポイントを定義しました。 exclude certain endpoints from the HAL browserの方法も見てきました。

APIを定義した後、テストデータを入力し、HALブラウザーの助けを借りて詳細に調査しました。 HALブラウザーの構造、およびAPIをステップスルーしてそのデータを探索できるUIコントロールを確認しました。

いつものように、コードは利用可能ですover on GitHub.

TOC