SpringRESTおよびHALブラウザー

投稿日: 2019-10-18 2022-11-10
タグ: REST, Spring

1. 概要

このチュートリアルでは、HALブラウザを紹介する前に、 HALとは何か、なぜそれが役立つのかについて説明します。

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

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

2. HALとHALブラウザ

JSONハイパーテキストアプリケーション言語、またはHALは、がAPI内のリソース間のハイパーリンクに一貫性のある簡単な方法を提供する単純な形式です。 REST APIにHALを含めると、本質的に自己文書化されるだけでなく、ユーザーにとってはるかに探索しやすくなります。

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

HALモデルは、2つの単純な概念を中心に展開しています。

リソース、には次のものが含まれます。

関連するURIへのリンク
埋め込みリソース
州

リンク：

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

HALブラウザーは、HALを開発したのと同じ人によって作成され、はRESTAPIをトラバースするためのブラウザー内GUIを提供します。

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

3. 依存関係

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

まず、Mavenベースのプロジェクトの依存関係：

<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-rest-hal-explorer</artifactId>
    <version>3.4.1.RELEASE</version>
</dependency>

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

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

4. シンプルなRESTAPIの構築

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リポジトリの紹介

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

このClassは、簡単なCRUDコマンドに加えて、ページングおよびソート機能をすぐに使用できるようにします。

@Repository
public interface BookRepository extends PagingAndSortingRepository<Book, Long> {

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

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

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

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

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

2番目のエンドポイントにはexport=false属性が含まれていることに注意してください。この属性は、このエンドポイントに対して生成されるHALリンクを停止し、HALブラウザーからは使用できなくなります。

最後に、 ApplicationRunner インターフェイスを実装するクラスを定義することにより、Springの開始時にデータをロードします。コードはGitHubにあります。

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

Springを使用してRESTAPIを構築する場合、HALブラウザーのセットアップは非常に簡単です。依存関係がある限り、Springはブラウザーを自動構成し、デフォルトのエンドポイントを介して使用できるようにします。

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

6. HALブラウザを使用したRESTAPIの調査

HALブラウザーは、エクスプローラーとインスペクターの2つの部分に分かれています。各セクションを個別に分析して説明します。

6.1. HALエクスプローラー

聞こえるように、エクスプローラーは現在のエンドポイントに関連するAPIの新しい部分を探索することに専念しています。検索バーと、現在のエンドポイントのカスタムリクエストヘッダーとプロパティを表示するテキストボックスが含まれています。

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

6.2. リンクの使用

/ books エンドポイントに移動すると、既存のリンクを表示できます。

これらのリンクは、隣接するセクションの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エンドポイントを示しています。エクスポートしないように定義したため、author-containsエンドポイントが欠落していることに注意してください。

6.3. 埋め込まれたリソースの表示

埋め込みリソースには、 /booksエンドポイント上の個々の書籍レコードの詳細が表示されます。各リソースには、独自のプロパティおよびリンクセクションも含まれています。

6.4. フォームの使用

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

タイトルのフォームは次のとおりです-エンドポイントが含まれています：

カスタムURIは、タイトルに「Java」という単語が含まれている20冊の本の最初のページを返します。

6.5. ハルインスペクター

インスペクターはブラウザーの右側を構成し、応答ヘッダーと応答本文。これ HALデータは、リンクと埋め込みリソースをレンダリングするために使用されますチュートリアルの前半で見たものです。

7. 結論

この記事では、HALとは何か、なぜそれが役立つのか、そしてなぜそれが優れた自己文書化RESTAPIの作成に役立つのかを要約しました。

PagingAndSortingRepository を実装し、独自のエンドポイントを定義する、Springを使用した単純なRESTAPIを構築しました。また、HALブラウザから特定のエンドポイントを除外する方法も確認しました。

APIを定義した後、テストデータを入力し、HALブラウザーを使用して詳細に調査しました。 HALブラウザーがどのように構成されているか、およびAPIをステップスルーしてそのデータを探索できるようにするUIコントロールを確認しました。

いつものように、コードはGitHubでから入手できます。

getdocs

13036