as:uploadMedia specification proposal

Based on content available in ActivityPub specification before https://github.com/w3c/activitypub/commit/fae6a56a8dcba9de69374aa7ae0bef565217e5c7

Servers MAY implement this feature. To accomplish this, a client must submit a multipart/form-data request to the uploadMedia user's endpoint on their ActivityStreams actor object.

A client should expect that it must be properly authenticated in order to be able to upload media.

The submitted form data should contain two parts / fields:

file
The file being uploaded
object
An optional skeleton for an ActivityStreams object to be finalized by the server

Assuming that the server accepts the request and that the user was appropriately authorized to upload media, servers MUST respond with a 201 Created if the submitted media is immediately available or a 202 Accepted if the server is still processing the submitted media. The response MUST contain a Location header pointing to the new or to be created object's id,
OR if considered a temporary transient object by the implementation, a copy of the object into the response body.

The server, having done any appropriate processing on the received file and putting it in place, transforms the object. In particular, servers SHOULD include the uploaded and/or processed file paths in the object's url property.

(Examples to be included; implementation-side documentation example: https://git.pleroma.social/pleroma/pleroma/-/merge_requests/3056/diffs)

Was wondering a bit about the case of the object potentially added into the actor’s outbox (and do related federation).

I think there is two ways to address it:

  1. Server never add into the outbox, the client decides to do so
  2. Server adds it into the outbox if the object has addressing (defaults to no addressing if object is absent)
  3. Server adds it into the outbox only if the object is wrapped into a Create activity

Currently Pleroma treats uploadMedia as a simple endpoint with the object being returned being something to be reused by the client later on as an attachment (or maybe a standalone object) so I personally would tend to go for option 1 but others (like PixelFed/Peertube/… and maybe Friendica as there is an media collection) might want option 2 or 3.

For now I’m writing an example with no addressing.

Extra thoughts:

  • What happens if the upload worked but the client never received the response?
  • What happens if you want to upload multiple files for one object?

Q: Pushing Activities later on? (APConf2020 talks)
A: AP extension? Which could also be useful to Delete objects for post expiration.