Allow media endpoint to return alternative / automatically generated files

[Zegnat]

Background

This is a spin-off from a question by @00dani:

[…] i'm pondering uploading .bmp files from a 3ds, which is incapable of converting to .png - would it be acceptable for the media endpoint to perform the conversion to .png instead?

@kevinmarks gives another example of server-side variant generation:

Scaling images is another case - you often want a thumbnail and full size, or other variants tuned to layout

Proposal

I would propose allowing the media endpoint to return alternative variants alongside the uploaded resource as follows:

HTTP/1.1 201 Created
Location: https://media.example.com/file/ff176c461dd111e6b6ba3e1d05defe78.bmp
Link: https://media.example.com/file/ff176c461dd111e6b6ba3e1d05defe78.png; rel="alternate"; type="image/png"

This could be extended with the sizes parameter, following the HTML Standard for its value, though I am not 100% sure how compatible this is with HTTP standards:

HTTP/1.1 201 Created
Location: https://media.example.com/huge-photo.png
Link: https://media.example.com/large/huge-photo.png; rel="alternate"; type="image/png"; sizes="1920x1080"
Link: https://media.example.com/medium/huge-photo.png; rel="alternate"; type="image/png"; sizes="960x540"
Link: https://media.example.com/small/huge-photo.png; rel="alternate"; type="image/png"; sizes="256x144"

The client may then check if more appropriate variants have been made available by the server. And as per normal the media endpoint may chose to purge any files that are left unused.

The addition of Link headers to the response is 100% backwards compatible with the current specification.

Reference specifications

According to RFC 7231 it is fine for a server to return a 201 Created response when “one or more” files have been created. This response may contain “links” to those files. It may then define several URLs within the response as long as the primary file “is identified by […] a Location header”. By having the Location header always point to the uploaded file it is easy to comply with this.

There is no specification for how to link to the alternative files, but there is a note for 300 Multiple Choices that I’ve taken inspiration from:

It is possible to communicate the list [of alternative representations] using a set of Link header fields [RFC5988], each with a relationship of "alternate", […]

[00dani]

It's worth pointing out that the Micropub specification already advises providing Link headers in the response when creating a post or other microformats2 object that has several URLs:

If the target also provides a shortlink, or if it syndicated the post to another location, the Micropub endpoint may return additional URLs using the HTTP Link header, along with an appropriate "rel" value. For example, it can return the short URL of a post by responding with:

Link: <http://aaron.pk/xxxxx>; rel="shortlink"

or can include the location of the syndicated post with:

Link: <https://myfavoritesocialnetwork.example/aaronpk/xxxxxx>; rel="syndication"

Providing alternative formats and sizes as Links on the media endpoint response isn't quite the same thing, but it does seem to fit quite well. 😄