A Custom Media Type for a Spring REST API – 为Spring REST API定制的媒体类型

最后修改: 2016年 12月 30日


1. Overview


In this tutorial, we’re going to take a look at defining custom media types and producing them by Spring REST controller.

在本教程中,我们将看看如何定义自定义媒体类型,并通过Spring REST控制器生产它们。

A good use case for using custom media type is versioning an API.


2. API – Version 1

2.API – 版本1

Let’s start with a simple example – an API exposing a single Resource by id.


We’re going to start with a Version 1 of the Resource we’re exposing to the client. In order to do that, we’re going to use a custom HTTP header – “application/vnd.baeldung.api.v1+json”.


The client will ask for this custom media type via the Accept header.

客户端将通过Accept 头询问这个自定义媒体类型。

Here’s our simple endpoint:


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

Notice the produces parameter here – specifying the custom media type that this API is able to handle.


Now, the BaeldungItem Resource – which has a single field – itemId:


public class BaeldungItem {
    private String itemId;
    // standard getters and setters

Last but not least let’s write an integration test for endpoint:


public void givenServiceEndpoint_whenGetRequestFirstAPIVersion_then200() {
      .get(URL_PREFIX + "/public/api/items/1")

3. API – Version 2

3.API – 第二版

Now let’s assume that we need to change the details that we’re exposing to the client with our Resource.


We used to expose a raw id – let’s say that now we need to hide that and expose a name instead, to get a bit more flexibility.


It’s important to understand that this change is not backwards compatible; basically – it’s a breaking change.


Here’s our new Resource definition:


public class BaeldungItemV2 {
    private String itemName;

    // standard getters and setters

And so, what we’ll need to do here is – migrate our API to a second version.


We’re going to do that by creating the next version of our custom media type and defining a new endpoint:


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

And so we now have the exact same endpoint, but capable of handling the new V2 operation.


When the client will ask for “application/vnd.baeldung.api.v1+json” – Spring will delegate to the old operation and the client will receive a BaeldungItem with a itemId field (V1).

当客户端将要求“application/vnd.baeldung.api.v1+json” – Spring将委托给旧操作,客户端将收到一个带有itemId字段(V1)的BaeldungItem

But when the client now sets the Accept header to “application/vnd.baeldung.api.v2+json” – they’ll correctly hit the new operation and get back the Resource with the itemName field (V2):

但是,当客户端现在将Accept头设置为“application/vnd.baeldung.api.v2+json” – 他们会正确地点击新的操作,并获得带有itemName字段的资源(V2)。

public void givenServiceEndpoint_whenGetRequestSecondAPIVersion_then200() {
      .get(URL_PREFIX + "/public/api/items/2")

Note how the test is similar but is using the different Accept header.


4. Custom Media Type on Class Level


Finally, let’s talk about a class-wide definition of the media type – that’s possible as well:


  value = "/", 
  produces = "application/vnd.baeldung.api.v1+json"
public class CustomMediaTypeController

As expected, the @RequestMapping annotation easily works on class level and allows us to specify the value, produces and consumes parameters.

正如预期的那样, @RequestMapping 注解很容易在类级别上工作,并允许我们指定valueproducesconsumes参数。

5. Conclusion


This articles illustrated examples when defining Custom Media Types could be useful in versioning public API.


The implementation of all these examples and code snippets can be found in the GitHub project.