Multiple Responses with the same media-type & status code



I’d like to create an API that is an intermediary to multiple back-end systems and supports both new and legacy clients. Since some of the legacy client are expecting a different response format I plan to basically “template” the response using different schemas according to what the client expects.

In my use case both responses are application/json but depending on a query parameter or a HEADER I would toggle which schema to respond to the client.

In the documentation I only see that you can have multiple responses if either:

  1. the media type
  2. the response code

is different.

But for my purpose both are application/json and both are 200.

What do you recommend to support multiple schemas?

In IRC @ddossot recommended:

in your case you probably want a different media type on the response though
since you pass the version in the Accept header
you probably have the version in a custom media type
so you probably have different media types for the different versions of the response
it would be strange to version the media type in the Accept header but not in the response Content-Type no?
because if you use the same media type for all different response schemas, how can the client know what it’s dealing with?

So that would mean that I would set multiple schemas based on different media types such as:

  • application/json+format1
  • application/json+format2

Is that the recommended approach?


This seems like the perfect solution, and I agree with @ddosot. After all, according to your description, your clients are expecting different response formats, not completely different responses representing different things. So you’re really talking about returning different representations of the resources based on what the client requested in the Accept header, to which the server should respond with the appropriate Content-Type header, and that’s exactly the semantics of the media type in RAML.

BTW I would think your media types should be more like:

  • application/format1+json
  • application/format2+json

See for more info.