Skip to content

Reusable media types #2845

@peteraritchie

Description

@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.)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Moved to MoonwalkIssues that can be closed or migrated as being addressed in MoonwalkNeeds attentionThe author has replied and people with triage rights should take action.media and encodingIssues regarding media type support and how to encode data (outside of query/path params)re-use: ref-everywhereRequests to support referencing in more / all places

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions