Read RestTemplate Accept header from entity annotation [SPR-12096]

[spring-projects-issues]

Christopher Smith opened SPR-12096 and commented

Current best practice is to version REST APIs by media type (application/vnd.example.person-v1+json), but the RestTemplate does not provide a simple mechanism for indicating the Accept header for an entity type when using a general-purpose converter (such as Jackson). Instead, the AcceptHeaderRequestCallback will add all potentially matching media types to the Accept header.

It should be possible to annotate an entity class to specify the media type that RestTemplate will request from the server so that older clients will not send an unversioned request that they can't understand:

@EntityMediaType("application/vnd.example.person-v1+json")
public class Person {
    // stuff
}

---

Affects: 4.0.6

Issue Links:

• Introduce proxy-based REST client similar to HttpInvokerProxyFactoryBean [SPR-12131] #16747 Introduce proxy-based REST client similar to HttpInvokerProxyFactoryBean

0 votes, 5 watchers

[spring-projects-issues]

Rossen Stoyanchev commented

What about setting the supportedMediaTypes property on the converter?

[spring-projects-issues]

Christopher Smith commented

That approach is cumbersome and, without completely hand-configuring the template, unreliable. In my case, the standard Jackson 2 mapper is perfectly sufficient for the actual conversion, and at a minimum I'd have to create a template without default converters (because the standard converter would add Accept: application/json, which might return the wrong version for the entity class) and write and register a converter for every single class I want to use with the template. Instead, I just want to declaratively specify a different Accept type (which can't currently be overridden, just appended to, with additional converters) on the single class in question (not in some companion class or external configuration) and run the conversion through the usual utilities.

[spring-projects-issues]

Rossen Stoyanchev commented

I guess what I was getting at is do you need to use different versions on different entities in the same app?

Configuring converters on the RestTemplate overrides defaults. So you'll need to list the converters you want, which is really straight forward and only done once. The ability to apply different versions on different entities IMO would be a stronger requirement for having some such annotation. Hence my question.

[spring-projects-issues]

Christopher Smith commented

I'm not sure I understand your question. Each entity class has its own (versioned) media type, but besides that, the out-of-the-box converter's behavior handles everything perfectly; listing converters requires writing, instantiating, and updating converter classes that do nothing except narrow the Accept type.

I would expect to use the same RestTemplate instance for all of the REST interactions with a Web application, but that template would be handling requests for a number of different entity classes with distinct media types.

[spring-projects-issues]

Rossen Stoyanchev commented

Okay I see your point. We can consider ways to improve working with versioned media types. One concern with the annotation is the ability to use it with more than one version but I can see that a single version is the 80% (common) case. When changing versions you would have to make sure the versions in all entity annotations are updated accordingly, which seems like a chore although I don't have any better ideas.

Note that there is also the option to use the RestTemplate's exchange methods, essentially passing a RequestEntity with the Accept header set, but considering that this is required for every operation with a response entity, it amounts to bypassing the more convenient RestTemplate methods by HTTP method wholesale.

[spring-projects-issues]

Christopher Smith commented

Generally speaking, the Java entity class will correspond to a specific API version, since the server side will need to be able to distinguish between representation classes for different versions. I'm actually using a rest.v0 package to separate these. In the unusual case where an entity class is forward-compatible, it might make sense for the annotation to be multi-valued, but since you have to tell the template ahead of time which class to deserialize onto (no inference from the media type), there wouldn't be any ambiguity.

[spring-projects-issues]

Rossen Stoyanchev commented

After some internal discussion the prevailing opinion is that such an annotation is not a good fit for use with the RestTemplate and would be too narrowly defined. It would be a better candidate for a higher-level REST programming model for example such as the one proposed here #16747.

Note also that it would be trivial for you to add such support by overriding the acceptHeaderRequestCallback method.