Parameters for Media Types

Parameters for Media Types

Media Types can support parameters. Yet, to work with them in OpenAPI, one must define them statically against each media type. This has the unfortunate side effect of discouraging use of media type parameters by making them clumsy to manage within the API spec.

content:
  text/plain; charset=utf-8:
    ...
  text/plain; charset=iso-8859-1:
    ...

Without a way to express the parameter, it has little or no semantic value for OpenAPI. Minor variations look like completely different media types. There is little room for negotiation over content parameters unless the API author takes the time to spell out each supported parameter as its own type.

Media Type parameters could be useful in some obvious ways:

• versioning of the media type
• specifying a 'profile' for the media type as described in RFC6906
• negotiating support for embedded resources (i.e. HAL (https://tools.ietf.org/html/draft-kelly-json-hal-08)) , hypermedia style, or level of completeness of a representation.

Private and vendor media types might better manage breaking changes by supporting multiple versions of representation without ever changing endpoints and methods. Perhaps there could be benefits to QA and regression test tooling, being able to validate support for the diversity of representation styles in the API contract. This could be had without having to iterate every parameter combination as a separate media type.

Examples

Versioning

Accept: application/vnd.example-schema+json; version=1.0.4

content:
  application/vnd.example-schema+json:
    parameters:
      version:
        type: string
        required: false
        description: |
          The version of the representation.
        default: 1.1.0
        enum:
          - 1.0.3
          - 1.0.4
          - 1.1.0
    schema:
    	$ref: "https://schemas.example.com/example"

Profile identification

Accept: application/vnd.example-schema+json; profile=https://schemas.example.com/example/profiles/bob

content:
  application/vnd.example-schema+json:
    parameters:
      profile:
        type: string
        required: false
        description: |
          The profile (rfc6906) for the representation.
        default: "https://schemas.example.com/example/profiles/alice"
        enum:
          - "https://schemas.example.com/example/profiles/alice"
          - "https://schemas.example.com/example/profiles/bob"
    schema:
    	$ref: "https://schemas.example.com/example"

Hypermedia style selection

Accept: application/vnd.example-schema+json; hypermedia=HAL

content:  
  application/vnd.example-schema+json:
    parameters:
      hypermedia:
        type: string
        required: false
        description: |
          Hypermedia Style.  Indicates whether links and other supplemental
          resource detail are provided in the representation.
        default: JSON_HYPERSCHEMA
        enum:
          hypermedia:
            - NONE
            - HAL
            - JSON_HYPERSCHEMA
    schema:
    	$ref: "https://schemas.example.com/example"

Added after the original issue report
I am inspired by what I read on Roy Fielding's blog entry "REST APIs must be Hypertext Driven".

"A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]"

If I understand him correctly, enriching OpenAPI's ability to semantically express media type parameters would improve its ability to convey the kinds of interactions Mr. Fielding expected to be inherent in the resource or resource representation, rather than in other parts of the HTTP message. Conversely, not supporting media type parameters might limit OpenAPI's ability to articulate a nuanced RESTful concept.

The issue names no files, tests, or implementation entry point. Begin by reviewing the specification's current media type and parameter definitions, then compare them with the examples and HTTP negotiation use cases described here; done means reaching a decided, precise way to express and validate media type parameters in OpenAPI.