Spring RESTとHALブラウザ

1.概要

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

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

最後に、HALブラウザを使用して、REST APIを調べ、その中に含まれているデータをどのようにトラバースするかを見つけます。

2. HALとHALブラウザ

JSON Hypertext Application Language (HAL)は、 私たちのAPIの リソース間のハイパーリンクへの一貫した簡単な方法を提供するシンプルなフォーマットです。 REST APIにHALを含めると、本質的に自己文書化されるだけでなく、ユーザーにとってもはるかに探索しやすくなります。

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

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

以下を含む リソース、

  • 関連するURIへのリンク

埋め込みリソース

リンク:

  • ターゲットURI

  • リンクへの関係、またはrel

  • 減価償却に役立つ他のいくつかのオプションのプロパティ

交渉など

HALブラウザはHALを開発した同じ人によって作成されたもので、 REST APIを横断するためのブラウザ内GUIを提供します

単純なREST APIを構築し、HALブラウザに接続して機能を調べます。

3.依存関係

以下は、HALブラウザをREST APIに統合するために必要な単一の依存関係です。 APIの残りの依存関係はhttps://github.com/eugenp/tutorials/blob/master/spring-rest-hal-browser/pom.xml[GitHub code]にあります。

まず、https://search.maven.org/classic/#search%7Cgav%7C1%7Cg%3A%22org.springframework.data%22%20AND%20a%3A%22spring-data-rest-hal-browser%22[依存関係]Mavenベースのプロジェクトの場合:

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

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. 単純データモデル

この例では、ライブラリでさまざまな書籍を閲覧するための簡単なREST APIを設定します。

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

@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エンティティからデータを取得するように指定できます。

このクラスは、簡単な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リポジトリの詳細を知りたい場合は、https://www.baeldung.com/spring-data-repositories[こちら]を参照してください。

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

  • __findByTitleContaining - クエリを含む本を __返します

タイトルに含まれる ** findByAuthorContaining – は、データベースから書籍を返します。

本の著者は、クエリを含みます

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

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

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

Springを使用してREST APIを構築する場合、HALブラウザの設定は非常に簡単です。依存関係がある限り、Springはブラウザを自動設定し、デフォルトのエンドポイントから利用できるようにします。

今実行する必要があるのは、プレス実行してブラウザに切り替えることだけです。 HALブラウザは http://localhost:8080/ で利用可能になります。

6. HALブラウザを使ったREST APIの検討

  • HALブラウザはエクスプローラとインスペクタ** の2つの部分に分けられます。各セクションを個別に分類して探ります。

6.1. HALエクスプローラ

おわかりのように、エクスプローラは 現在のエンドポイント に関連して 私たちのAPIの新しい部分を探求することに専念しています。現在のエンドポイントの カスタム要求ヘッダーとプロパティ** を表示するためのテキストボックスだけでなく、検索バーも含まれています。

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

6.2. リンクを使う

__/books __endpointに移動すると、既存のリンクを見ることができます。

画像、幅= 557、高さ= 267

これらの リンクは隣接するセクションの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__エンドポイントを示しています。

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

Embedded Resourcesは、私たちの /books エンドポイントで 個々の本の記録の詳細 を示しています。各リソースには、独自の __Properties および Links __sectionも含まれています。

画像、幅= 565、高さ= 416

6.4. フォームを使う

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

これが __title-contains __endpointのフォームです。

HALブラウザ選択フォーム、幅= 542、高さ= 472

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

6.5. ハルインスペクタ

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

7.まとめ

この記事では、HALとは何か、なぜそれが便利なのか、そしてなぜそれが** 優れた自己文書化REST APIを作成するのに役立つのか?

Springを使って PagingAndSortingRepository を実装する簡単なREST APIを作成し、独自のエンドポイントを定義しました。

  • HALブラウザから特定のエンドポイントを除外する方法** も確認しました。

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

いつものように、コードは利用可能です https://github.com/eugenp/tutorials/tree/master/spring-rest-hal-browser [over GitHubで。