micropub media endpoint

From IndieWeb
Jump to: navigation, search

micropub media endpoint is a Micropub endpoint that exclusively handles file uploads and returns a URL that can be used in a subsequent Micropub request.

Indieweb Examples

  • Aaron Parecki has used a standalone media endpoint since 2016-11-02. The source code is available on GitHub
  • Marty McGuire has used Spano as a Micropub media endpoint on his site since 2017-01-26.
  • Greg V has used a standalone (but part of sweetroll project) media endpoint since 2017-05-11. It supports image processing and S3 storage. It can work on AWS Lambda, though it's on a normal server currently. Source is available on GitHub.


Discovery via link rel

As Micropub Media Endpoints are often implemented as separate services from a site's "main" Micropub endpoint, it may be useful to allow Micropub clients to discover the media endpoint without needing to query the "main" endpoint at all.

Discovery of a Micropub Media Endpoint could be accomplished like Micropub endpoint discovery, with HTTP Link headers:

Link <https://aaronpk.example/micropub/media>; rel="micropub_media"

Or via HTML Link tag:

<link rel="micropub_media" href="https://aaronpk.example/micropub/media">


Add Media support to a site whose Micropub server is missing it – With the current Media Endpoint discovery algorithm, a micropub client must ask the server whether a media endpoint is available. Micropub/Servers, especially those that create posts for static sites like Jekyll, don't offer media endpoint support. If a user sets up a separate micropub media endpoint, they must configure their "main" micropub server to make it available to clients - a change that could require them to edit the code of the micropub server.

Standalone Media EndpointIndigenous for Android supports uploading files to a media endpoint and copying the URL to the clipboard for use in any context. Separating media endpoint discovery from "main" micropub server discovery would allow micropub clients to manage media without also managing posts on the site.

This is currently implemented by:

And consumed by:

Query the last thing uploaded

A Micropub client should be able to query the Media Endpoint to find the last photo uploaded. This would allow a post interface to appear with the photo pre-populated. This mechanism ends up treating the Media Endpoint as a kind of account-level clipboard, so you could upload a photo from one device then finish the post on another device.

This also gets closer in line with the way the Wordpress uploader works, where images are stored in a media gallery and can be added to posts later. Might need to explore that API to see how they handle querying the list of media.

GET /media-endpoint?q=last
Authorization: Bearer XYZ123

Content-type: application/json

  "url": "....."

This is currently implemented by:

And consumed by:

  • Quill - queries the media endpoint to find the last uploaded image and pre-populates the photo in the note interface

Response Body

The Micropub spec doesn't define a particular response body when uploading to the media endpoint. It only defines that the response include the created URL in the Location header. However, some tools are easier to work with if they can use the response body instead of having to parse the HTTP headers.

This should also be the same response format used when querying the endpoint to find the last thing uploaded.

If the Accept header prefers text/plain then the response body is just the full URL. Otherwise, a JSON object with a "url" property is returned.

Content-Type: text/plain

Content-Type: application/json

  "url": "https://media.aaronpk.com/filename.jpg"

This response currently produced by:

  • Aaron Parecki in his media endpoint on media.aaronpk.com
  • Greg V in sweetroll — instead of "url" there's a JSON structure with a bunch of stuff. For photos: "width", "height", "meta" (metadata extracted by exiv2), "palette" (prominent colors via vibrant), "tiny_preview" (data uri of a tiny WebP preview) and most importantly "source" (links to the actual image in different formats).
  • WordPress Micropub currently returns the parsed metadata about the media file and the alternate sizes currently generated by WordPress on a file upload. It is not specifically reformatted for Micropub at this time.
  • Jonathan LaCour added support for this response in Known in November 2018.

And consumed by:

  • Aaron Parecki - a iOS Workflow that I created to upload to my media endpoint requests a text/plain response and uses the body as the URL, copying it to the clipboard. that was easier than adding a JSON parser to the Workflow.
  • Greg V - sweetroll does rich photo display based on the data generated by the endpoint.


Where supported, suggesting that an Endpoint accept name, category, and description optionally. This would take the form of a form encoded submission only. I do not want to suggest complicated properties being sent to photos.

The practical reason is that naming photos allows them to be retrieved.

Tagging would allow a query for images that matched a tag for a possible suggested image library search if someone wanted to implement that into a client.

Query media by URL

inari allows you to query for media by URL. The request/response looks like this:

GET /media-endpoint?q=source&url=https://micropub.funabashi.co.uk/media/2018/8f4d5ef8e12e608eba1605bcf09fa086.jpg
Authorization: Bearer XYZ123
    "uid": "abffa609-df23-4f4c-a117-f762777e97ec",
    "url": "https://micropub.funabashi.co.uk/media/2018/8f4d5ef8e12e608eba1605bcf09fa086.jpg",
    "file_key": "2018/8f4d5ef8e12e608eba1605bcf09fa086.jpg",
    "file_hash": "8f4d5ef8e12e608eba1605bcf09fa086",
    "mime_type": "image/jpeg",
    "date_time": "2018-05-20T22:31:50Z",
    "lat": 53.830398399972225,
    "lng": -1.5584950999722222

The important things here are date_time and lat, lng which has been extracted from the photo EXIF data. Clients can then add this data to posts. j4y_funabashi

WordPress Micropub Plugin implements q=source and url= for the media endpoint. It returns the WordPress media metadata and will likely change this when there is a clearer return standard.

Query media list

inari allows you to query for a media list. Currently this shows the latest 30 media files uploaded, pagination is to follow.

GET /media-endpoint?q=source
Authorization: Bearer XYZ123
    "items": [
            "uid": "8535f86b-3a4a-4d50-8a33-ed71050b2f12",
            "url": "http://mpserver/media/2018/d45f435b2ce3ea97cf35054122736751.jpg",
            "file_key": "2018/d45f435b2ce3ea97cf35054122736751.jpg",
            "file_hash": "d45f435b2ce3ea97cf35054122736751",
            "mime_type": "image/jpeg",
            "date_time": "2018-10-03T16:26:24Z",
            "lat": 48.14296338888889,
            "lng": 17.115262972222222


  • WordPress Micropub Plugin implements q=source as well as limit to specify the number of things to return. It returns WordPress media metadata until there is a discussion of what to return to consume.

See Also