SpringRESTAPIのカスタムメディアタイプ

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

1. 概要

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

カスタムメディアタイプを使用するための良いユースケースは、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を2番目のバージョンに移行することです。

これを行うには、カスタムメディアタイプの次のバージョンを作成し、新しいエンドポイントを定義します。

@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は古い操作に委任し、クライアントはBaeldungItemと itemId フィールド（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のバージョン管理に役立つ可能性があります。

これらすべての例とコードスニペットの実装は、GitHubプロジェクトにあります。

getdocs

13036