How to encode a parameter in media-type

We have an existing API that uses vendor specific media types to indicate the API version used by the client, to the server.

e.g. Content-Type and Accept would both be “application/vnd.company.component.v{version}+json”

Trouble is, when I try to use this under the body: I get the error: invalid media type.
Is it possible to do this in RAML?

#%RAML 1.0
---
baseUri: https://company.com/api
version: 2.0.0
#...
/resource
 post:
  body:
   application/vnd.company.component.v{version}+json: # error on this line
    type: request
    required: true
  responses:
   202:
    body:
      application/vnd.company.component.v{version}+json # same error on this line
       schema: myschema
#...

Thanks!

The only way (I can think of) to set media types dynamically the way you described would be to define one or multiple Resource Types and pass the version as a resource type parameter. This may not work though if what you intend by version is a wildcard or free form combination of digits and ..

Is this media type registered or part of any standard definition? If so, would you mind sharing a link?

Hi @jstoiko

Thanks for the info. I’ll have a look into resource types.
The media type is part of an internal API so there is no registration.

I wonder if this is even valid though. There is a special way to pass parameters such as versions in content/media types. It’s usually what follows the ; after the (...)/(...) pattern. If you have control over that API, I would suggest looking into whether this is the best approach.

Is there such a thing as “valid” for a REST interface? (e.g. the HTTP RFC doesn’t prevent this usage)

There are many many pages that document 3 main ways or permutations thereof for versioning requests, with this being one of those 3 (e.g. https://www.baeldung.com/rest-versioning).
The approach of changing a part of the URL is not a runner for us due to various reasons, so use of a header is the other common option.

With hindsight (we can’t go back and change the implementation now, we are merely documenting an existing interface here), your mention of putting the version after the “;” probably make the string in the Content-Type clearer, but we would still need to distinguish between these versions in the RAML if it is indeed to document the interface and the versions thereof correctly.

You’re right. What I meant is that if that version in the Content-Type meets the definition of “dynamic” (as in changing often), then it may not be best practice to define it there. The link you shared provides more context though. I would advise setting the version (v1, v2, etc) in the RAML resource or resourceType (as a resourceType parameter) since this is not something dynamic but rather a versioning of the resource definition, which, if it changes, will need to be changed in the RAML API definition as well anyway since the schema/type definition would change as well.