Spring Bootのコンテンツネゴシエーション入門：AcceptとContent-Typeの違いと使い方

1. コンテンツネゴシエーションとは何か？

1. コンテンツネゴシエーションとは何か？

Spring Bootにおけるコンテンツネゴシエーションとは、クライアントの希望するレスポンス形式（たとえばJSONやXMLなど）に応じて、適切なフォーマットでデータを返す仕組みです。REST APIの開発では非常によく使われる機能です。

この仕組みにより、URLを変えることなく、ヘッダーの指定だけで出力形式を制御できます。

2. AcceptとContent-Typeの違い

2. AcceptとContent-Typeの違い

HTTP通信では、AcceptとContent-Typeという2つの重要なヘッダーがあります。混同しやすいので、それぞれの役割を整理しましょう。

• Acceptヘッダー：クライアントが「どの形式のレスポンスが欲しいか」をサーバーに伝える。
• Content-Typeヘッダー：リクエストまたはレスポンスの「データの形式」を表す。

つまり、Acceptは要求（リクエスト）、Content-Typeは実際の中身（リクエストまたはレスポンス）の形式を表します。

3. Spring Bootのコンテンツネゴシエーションの動作

3. Spring Bootのコンテンツネゴシエーションの動作

Spring Bootでは、Acceptヘッダーを見て、内部でHttpMessageConverterを使って適切な形式でレスポンスを返してくれます。特別な設定をしなくても、Jackson（JSON用）やJAXB（XML用）が組み込まれているため、簡単に切り替えが可能です。

@RestController
public class SampleController {

    @GetMapping(value = "/data", produces = {MediaType.APPLICATION_JSON_VALUE, MediaType.APPLICATION_XML_VALUE})
    public SampleData getData() {
        return new SampleData("ネコ", 3);
    }
}

このようにproducesで複数の形式を指定することで、Acceptヘッダーの値に応じて自動的に出力形式が切り替わります。

4. AcceptヘッダーでJSONとXMLを切り替える

4. AcceptヘッダーでJSONとXMLを切り替える

クライアントから送るAcceptヘッダーの例を見てみましょう。たとえば、curlでのリクエストは次のようになります。

curl -H "Accept: application/json" http://localhost:8080/data
curl -H "Accept: application/xml" http://localhost:8080/data

これにより、SampleDataクラスのインスタンスがJSONまたはXML形式で出力されます。とても柔軟な設計ですね。

5. Content-Typeでリクエストのデータ形式を指定する

5. Content-Typeでリクエストのデータ形式を指定する

Content-Typeは主にPOSTやPUTリクエストで、サーバーに送信するデータの形式を伝えるために使います。Spring Bootでは以下のように指定します。

@PostMapping(value = "/create", consumes = MediaType.APPLICATION_JSON_VALUE)
public String createItem(@RequestBody Item item) {
    return "登録完了";
}

この場合、Content-Type: application/jsonがリクエストに含まれていないと、415 Unsupported Media Typeエラーになります。

6. application.ymlやapplication.propertiesでデフォルト設定を変える

6. application.ymlやapplication.propertiesでデフォルト設定を変える

Spring Bootでは、コンテンツネゴシエーションの戦略をapplication.ymlまたはapplication.propertiesで変更できます。

spring.mvc.contentnegotiation.favor-parameter=true
spring.mvc.contentnegotiation.parameter-name=type
spring.mvc.contentnegotiation.favor-path-extension=false
spring.mvc.contentnegotiation.media-types.json=application/json
spring.mvc.contentnegotiation.media-types.xml=application/xml

これにより、?type=jsonなどのパラメータで出力形式を指定できるようになります。初心者にも扱いやすいオプションです。

7. パス拡張子による形式指定は非推奨

7. パス拡張子による形式指定は非推奨

Spring Boot 2.6以降では、.jsonや.xmlなどの拡張子による出力指定はセキュリティ上の理由から非推奨となっています。代わりにAcceptヘッダーやクエリパラメータを使用しましょう。

これにより、予期しないファイル出力やルーティングの問題を防ぐことができます。

8. 独自フォーマットへの対応方法

8. 独自フォーマットへの対応方法

もしJSONやXML以外のフォーマット（たとえばCSVや独自形式）を返したい場合は、独自のHttpMessageConverterを実装してWebMvcConfigurerに登録することで対応できます。

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        converters.add(new CsvMessageConverter());
    }
}

こうすることで、Accept: text/csvを受け取った場合にCSV出力ができるようになります。

まとめ

まとめ

Spring Bootにおけるコンテンツネゴシエーションの理解を深める

この記事では、Spring BootでREST APIを開発する際に非常に重要となる コンテンツネゴシエーションの考え方について詳しく学んできました。 コンテンツネゴシエーションとは、クライアントとサーバーがやり取りする際に、 どのデータ形式でレスポンスやリクエストを扱うかを調整する仕組みです。 特にWeb APIでは、JSONやXMLといった複数の形式に対応できる設計が求められることが多く、 Spring Bootの標準機能を理解しておくことは非常に大切です。

Spring Bootでは、HTTPヘッダーであるAcceptとContent-Typeを正しく使い分けることで、 柔軟なデータ形式の切り替えが可能になります。 Acceptはクライアントが「どの形式でレスポンスを受け取りたいか」を指定し、 Content-Typeは「実際に送信されるデータの形式」を示すという役割の違いを理解することが、 コンテンツネゴシエーションを正しく扱う第一歩と言えるでしょう。

AcceptとContent-Typeを使い分ける実践的なポイント

記事中で解説したように、Spring Bootでは@GetMappingや@PostMappingの producesやconsumes属性を使うことで、 レスポンスやリクエストの形式を明示的に指定できます。 これにより、JSON専用のAPIやXML対応のAPIを安全に設計できるようになります。 特にREST APIでは、意図しない形式のリクエストを防ぐためにも、 Content-Typeのチェックは重要な役割を果たします。

また、Spring Bootが内部で利用しているHttpMessageConverterの存在を理解することで、 なぜJSONやXMLが自動的に変換されるのかが見えてきます。 JacksonやJAXBといったライブラリが裏側で動作していることを知っておくと、 エラーが発生した際の原因調査や拡張実装にも役立ちます。

設定ファイルによる柔軟な制御と注意点

application.propertiesやapplication.ymlを使えば、 コンテンツネゴシエーションの挙動をさらに細かく制御できます。 クエリパラメータで形式を指定する方法は、デバッグや簡易的なAPI利用に便利ですが、 セキュリティや将来の保守性を考えると、 基本はAcceptヘッダーを利用する設計が望ましいと言えます。

また、パス拡張子による形式指定が非推奨になっている理由を理解することも重要です。 安全で予測可能なAPI設計を行うためには、 Spring Bootの推奨する方法に沿った実装を心がけることが大切です。

まとめとしてのサンプルプログラム

ここで、今回学んだコンテンツネゴシエーションの基本を振り返るために、 JSONとXMLの両方に対応したシンプルなコントローラの例を確認してみましょう。 記事内で使用してきたクラスやアノテーションと同じ書き方になっています。

@RestController
public class SummaryController {

    @GetMapping(
        value = "/summary",
        produces = {
            MediaType.APPLICATION_JSON_VALUE,
            MediaType.APPLICATION_XML_VALUE
        }
    )
    public SampleData summary() {
        return new SampleData("イヌ", 5);
    }
}

このように設定しておけば、クライアントが送信するAcceptヘッダーに応じて、 自動的にJSONまたはXMLでレスポンスが返されます。 Spring Bootのコンテンツネゴシエーションを正しく理解していれば、 特別な処理を書かなくても柔軟なAPIを構築できることがわかります。