Spring REST APIのカスタムメディアタイプ

1. 概要

このチュートリアルでは、カスタムメディアタイプを定義し、Spring RESTコントローラーでそれらを作成する方法を見ていきます。

カスタムメディアタイプを使用するための良い使用例は、APIのバージョン管理です。

2. API –バージョン1

簡単な例から始めましょう–IDによって単一のリソースを公開するAPI。

クライアントに公開しているリソースのバージョン1から始めます。そのために、カスタムHTTPヘッダー（“application/vnd.example.api.v1+json”）を使用します。

クライアントは、Acceptヘッダーを介してこのカスタムメディアタイプを要求します。

簡単なエンドポイントは次のとおりです。

@RequestMapping(
  method = RequestMethod.GET,
  value = "/public/api/items/{id}",
  produces = "application/vnd.example.api.v1+json"
)
@ResponseBody
public exampleItem getItem( @PathVariable("id") String id ) {
    return new exampleItem("itemId1");
}

ここでproducesパラメータに注意してください–このAPIが処理できるカスタムメディアタイプを指定します。

ここで、exampleItemリソース–単一のフィールド–itemId：

public class exampleItem {
    private String itemId;

    // standard getters and setters
}

最後になりましたが、エンドポイントの統合テストを作成しましょう。

@Test
public void givenServiceEndpoint_whenGetRequestFirstAPIVersion_then200() {
    given()
      .accept("application/vnd.example.api.v1+json")
    .when()
      .get(URL_PREFIX + "/public/api/items/1")
    .then()
      .contentType(ContentType.JSON).and().statusCode(200);
}

3. API-バージョン2

ここで、リソースを使用してクライアントに公開する詳細を変更する必要があると仮定します。

以前は生のIDを公開していましたが、もう少し柔軟性を持たせるために、それを非表示にして名前を公開する必要があるとします。

この変更には下位互換性がないことを理解することが重要です。基本的に–それは重大な変化です。

新しいリソースの定義は次のとおりです。

public class exampleItemV2 {
    private String itemName;

    // standard getters and setters
}

したがって、ここで行う必要があるのは、APIを2番目のバージョンに移行することです。

これをcreating the next version of our custom media typeで行い、新しいエンドポイントを定義します。

@RequestMapping(
  method = RequestMethod.GET,
  value = "/public/api/items/{id}",
  produces = "application/vnd.example.api.v2+json"
)
@ResponseBody
public exampleItemV2 getItemSecondAPIVersion(@PathVariable("id") String id) {
    return new exampleItemV2("itemName");
}

これで、まったく同じエンドポイントができましたが、新しいV2操作を処理できます。

クライアントが“application/vnd.example.api.v1+json”を要求する場合– Springは古い操作に委任し、クライアントはitemIdフィールド（V1）を持つexampleItemを受け取ります。

ただし、クライアントがAcceptヘッダーを“application/vnd.example.api.v2+json” –に設定すると、新しい操作が正しく実行され、itemNameフィールド（V2）を使用してリソースが返されます。

@Test
public void givenServiceEndpoint_whenGetRequestSecondAPIVersion_then200() {
    given()
      .accept("application/vnd.example.api.v2+json")
    .when()
      .get(URL_PREFIX + "/public/api/items/2")
    .then()
      .contentType(ContentType.JSON).and().statusCode(200);
}

テストがどのように似ているかに注意してくださいが、異なるAcceptヘッダーを使用しています。

4. クラスレベルのカスタムメディアタイプ

最後に、メディアタイプのクラス全体の定義について説明しましょう。これも可能です。

@RestController
@RequestMapping(
  value = "/",
  produces = "application/vnd.example.api.v1+json"
)
public class CustomMediaTypeController

予想どおり、@RequestMappingアノテーションはクラスレベルで簡単に機能し、value、produces、およびconsumesパラメータを指定できます。

5. 結論

この記事では、カスタムAPIの定義がパブリックAPIのバージョン管理に役立つ場合の例を示しました。

これらすべての例とコードスニペットの実装はthe GitHub projectにあります。これはMavenプロジェクトであるため、そのままインポートして実行するのは簡単です。

TOC

Spring REST APIのカスタムメディアタイプ