Reusable media types

[peteraritchie]

AKA "Add mediaTypes to components".

Apologies if this is a horse already flogged; I couldn't find it, so please point me in the right direction if this is noise.

Context

REST and HATEOS

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)..,-%5BFailure%20here%20implies)

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations.

In OpenAPI I can specify endpoints that include request and response specifications/schemas that can include media types. Part of what I believe Roy Fielding has detailed is that with HATEOS that media types are more important than hierarchies. I read this to mean that any single operation may respond with a link/media-type relation and that it's more important that the receiver understands the media type than have a priori knowledge of a URI.

Suggestion, Ask, Issue

Adding individual media types to components would be hugely useful to support this sort of thing. (e.g.mediaTypes in components, but implementation isn't the important part.) A service could then operate with a canonical set of resource definitions then regardless what URI a requesting application uses it would understand the request and responses. This would enable servers to control their own namespace through media types and link relations (via Link header, etc.)

[handrews]

I think is too big of a change for 3.x, but it might be worth discussing over in the Moonwalk (4.0) repository, specifically:

• https://github.com/OAI/sig-moonwalk/discussions/30

I'm not entirely sure I understand the ask here – at least not well enough to update the Moonwalk discussions myself, so I'm not going to close it yet.

[peteraritchie]

I'll check that thread out in moonwalk.

[peteraritchie]

@handrews I'm not sure that thread totally subsumes this. I think it could, I'll see if I can communicate the concept in there...

[handrews]

@peteraritchie Is part of this just adding a section for Media Type Objects under the Components Object? Because that could be done in 3.2. But I feel like there's more here, and its not entirely clear to me how common Media Type Objects would be used unless you are avoiding resource-specific schemas.

[peteraritchie]

@handrews 3.2? Media Type Objects within Components would definitely add value in this context. I was avoiding suggesting a particular solution :). How would this be done in 3.2, or are you alluding to extensions?

[handrews]

@peteraritchie I think these two issues/discussions might address what you're getting at here:

• 3771 (extensibility for working with media types not directly addressed by the OAS)

• 3853 (general round-up of $ref-ing various components)

We could do more "put X in Components and allow $ref-ing it" in 3.2, although I suspect we will not in order to keep the implementation burden small. If 3.2 is well-received, we'll likely be able to do a small 3.3 that could maybe expand in this area. But we'll track that in #3853.

I am hoping that the proposal in #3771 covers what you meant by there being more than just $ref-ing Media Type Objects. The challenge with media type support is that there's no easy way to support new media types with extensions. Adding x- fields is not sufficient. We do support XML (sort-of) with extra Schema Object fields, but I don't think anyone considers that a model worth repeating for more types. We support form data with the Encoding Object, which is complicated and not suitable for other media types.

A registry (that could include how the XML and Encoding Objects work, but not be limited to those approaches) would allow defining how media types work in general, which is something we can't do right now. Is that what you were getting at with "reusable media types"? If so, would you be OK with closing this in favor of #3853 and #3771? Note that discussion 3771b will produce issues when we have an actionable plan - we're kind-of trying to move open-ended discussions to GitHub discussions and use issues for actionable things.

[handrews]

@peteraritchie I'm taking that thumbs up as "OK to close in favor of the other issues/discussions" – if that is not what you meant please feel free to comment and I can re-open.