1概要

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

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


2 API – バージョン1

簡単な例、つまり単一のリソースをIDで公開するAPIから始めましょう。

クライアントに公開しているリソースのバージョン1から始めます。そのためには、カスタムHTTPヘッダー（

“ application/vnd.baeldung.api.v1 + json”

）を使用します。

クライアントは

Accept

ヘッダーを介してこのカスタムメディアタイプを要求します。

これが私たちのシンプルなエンドポイントです。 

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

この

produces

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

さて、

BaeldungItem

リソース – これは単一のフィールドを持ちます –

itemId

: 

public class BaeldungItem {
    private String itemId;

   //standard getters and setters
}

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

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

3. API – バージョン2

それでは、リソースを使ってクライアントに公開する詳細を変更する必要があるとしましょう。

以前は生のIDを公開していました – 今度はそれを非表示にして代わりに名前を公開する必要があるとしましょう。もう少し柔軟にするためです。

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

これが私たちの新しいリソース定義です。 

public class BaeldungItemV2 {
    private String itemName;

   //standard getters and setters
}

したがって、ここでやらなければならないことは、APIを別のバージョンに移行することです。

  • カスタムメディアタイプの次期バージョンを作成** し、新しいエンドポイントを定義することでこれを実現します。 

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

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

クライアントが

“ application/vnd.baeldung.api.v1 + json”を要求するとき

– Springは古い操作に委任し、クライアントは

itemId

フィールドを持つ

BaeldungItem

を受け取ります（V1）。

しかし、クライアントが

Accept

ヘッダーを

“ application/vnd.baeldung.api.v2 json”に設定すると、新しい操作が正しく実行され、

itemName__フィールドでリソースが返されます（V2）。 

@Test
public void givenServiceEndpoint__whenGetRequestSecondAPIVersion__then200() {
    given()
      .accept("application/vnd.baeldung.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.baeldung.api.v1+json"
)
public class CustomMediaTypeController

予想通り、

@ RequestMapping

アノテーションはクラスレベルで簡単に機能し、

value

、

produces

、および

consumes

パラメーターを指定することができます。

5.まとめ

この記事では、カスタムメディアタイプの定義がパブリックAPIのバージョン管理に役立つ可能性がある場合の例を示しました。

これらすべての例とコードスニペットの実装はhttps://github.com/eugenp/tutorials/tree/master/spring-rest[GitHubプロジェクト]にあります。そのままインポートして実行します。