View source for SocialCG/ActivityPub/MediaUpload

The Media Upload mechanism defines a protocol for ActivityPub servers to support uploading document types to be referenced in activites, such as images, video or other binary data. To accomplish this, a client MUST submit a <code>multipart/form-data</code> message to the user's [[#uploadMedia|<code>uploadMedia</code>]] endpoint on their ActivityStreams profile object. (Unlike most client to server interactions, using this endpoint does not involve submitting to the [[#outbox|<code>outbox</code>]]). A client should expect that it must be properly authenticated in order to be able to upload media.

The <code>uploadMedia</code> endpoint is part of the ActivityPub <code>endpoints</code> mapping. See [[ActivityPub extensions#uploadMedia|ActivityPub extensions]].

The submitted form data should contain two parts / fields:

; file
: The media file file being uploaded.
; object
: A shell of an ActivityStreams object, which will 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 <code>201 Created</code> if the object is immediately available or a <code>202 Accepted</code> if the server is still processing the submitted media. The response MUST contain a <code>Location</code> header pointing to the new or to-be-created object's <code>id</code>.

The server, having done any appropriate processing on the received <code>file</code> and putting it in place, transforms the <code>object</code> that will be retrievable by the <code>id</code>. In particular, servers MUST append an <code>id</code> property to the object, and SHOULD include the uploaded and/or processed file paths in the object's <code>url</code> property. The server MAY wrap the shell object submitted by the user in a <code>Create</code> via [[#object-without-create|]] if appropriate and present this as the object pointed to by the forementioned <code>Location</code> header in the post-media-upload response.

Ben Bitdiddle just recorded a video of his friend's latest invention and wants to upload it to his ActivityPub-compatible social network to show it off. He wants to post a <code>Create</code> of a new <code>Video</code> object, but first he has to upload the video somewhere. Luckily the ActivityPub instance he is on supports the <code>uploadMedia</code> endpoint! In his client, he selects the video for upload and adds a title and a description and presses submit.

Ben's client takes a look at Ben's [[#actors|actor]] profile and finds the <code>uploadMedia</code> endpoint there.

<pre class="example highlight json">            {&quot;@context&quot;: &quot;https://www.w3.org/ns/activitystreams&quot;,
             &quot;type&quot;: &quot;Person&quot;,
             &quot;id&quot;: &quot;https://chatty.example/ben/&quot;,
             &quot;name&quot;: &quot;Ben Bitdiddle&quot;,
             &quot;preferredUsername&quot;: &quot;ben&quot;,
             &quot;summary&quot;: &quot;Constantly fidgeting with ones and zeroes.&quot;,
             &quot;inbox&quot;: &quot;https://chatty.example/ben/inbox/&quot;,
             &quot;outbox&quot;: &quot;https://chatty.example/ben/collections/outbox/&quot;,
             &quot;followers&quot;: &quot;https://chatty.example/ben/collections/followers/&quot;,
             &quot;following&quot;: &quot;https://chatty.example/ben/collections/following/&quot;,
             &quot;liked&quot;: &quot;https://chatty.example/ben/collections/liked/&quot;,
             &quot;endpoints&quot;: {
               &quot;id&quot;: &quot;https://chatty.example/ben/#endpoints&quot;,
               &quot;uploadMedia&quot;: &quot;https://chatty.example/ben/endpoints/uploadMedia/&quot;}}
          </pre>
Ben's client then constructs a shell ActivityPub object (this doesn't have the url for the video itself yet, but that's okay, because that will be added by the server) and submits it (as the <code>object</code>) along with the video (as the <code>file</code>) by <code>POST</code>'ing to the <code>uploadMedia</code> endpoint.

<pre class="example">            POST /ben/endpoints/uploadMedia/ HTTP/1.1
            Host: chatty.example
            Content-Type: multipart/form-data; boundary=bfe40faf4ef
            Authorization: Bearer XXXXXXXXXXX
  
            --bfe40faf4ef
            Content-Disposition: form-data; name=&quot;object&quot;
            Content-Type: application/ld+json; profile=&quot;https://www.w3.org/ns/activitystreams&quot;
  
            {&quot;@context&quot;: &quot;https://www.w3.org/ns/activitystreams&quot;,
             &quot;type&quot;: &quot;Create&quot;,
             &quot;actor&quot;: &quot;https://chatty.example/ben/&quot;,
             &quot;to&quot;: [&quot;https://chatty.example/ben/collections/followers/&quot;,
                    &quot;https://www.w3.org/ns/activitystreams#Public&quot;],
             &quot;object&quot;: {
               &quot;type&quot;: &quot;Video&quot;,
               &quot;name&quot;: &quot;A wireworld computer!&quot;,
               &quot;attributedTo&quot;: &quot;https://chatty.example/ben/&quot;,
               &quot;to&quot;: [&quot;https://chatty.example/ben/collections/followers/&quot;,
                      &quot;https://www.w3.org/ns/activitystreams#Public&quot;],
               &quot;summary&quot;: &quot;&lt;p&gt;My friend Conway and I went over to our friend
                              Silverman's place and saw the wireworld computer
                              he's been constructing.  Pretty crazy!&lt;/p&gt;
                           &lt;p&gt;Tomorrow we're going over to our friend Langton's
                              place and see that ant farm he's been working
                              on...&lt;/p&gt;&quot;}}
  
            --bfe40faf4ef
            Content-Disposition: form-data; name=&quot;file&quot;; filename=&quot;wireworld.webm&quot;
            Content-Type: video/webm
  
            ... (binary data) ...
            --bfe40faf4ef
          </pre>
Ben's client receives an HTTP response from the server with the status code <code>202 Accepted</code> since the video is still being transcoded. The response contains a <code>Location</code> header pointing at the url <code>https://chatty.example/ben/posts/d4152a7c/</code>. Sure enough, a few minutes later Ben's video shows up in his <code>outbox</code> with the rest of the fields filled in:

<pre class="example highlight json">            {&quot;@context&quot;: &quot;https://www.w3.org/ns/activitystreams&quot;,
             &quot;type&quot;: &quot;Create&quot;,
             &quot;id&quot;: &quot;https://chatty.example/ben/posts/d4152a7c/&quot;,
             &quot;actor&quot;: &quot;https://chatty.example/ben/&quot;,
             &quot;to&quot;: [&quot;https://chatty.example/ben/collections/followers/&quot;,
                    &quot;https://www.w3.org/ns/activitystreams#Public&quot;],
             &quot;object&quot;: {
               &quot;type&quot;: &quot;Video&quot;,
               &quot;id&quot;: &quot;https://chatty.example/ben/posts/6e69f564/&quot;,
               &quot;url&quot;: [
                 {&quot;type&quot;: &quot;Link&quot;,
                  &quot;href&quot;: &quot;https://chatty.example/media/6e69f564/wireworld-small.webm&quot;,
                  &quot;mediaType&quot;: &quot;video/webm; codecs=\&quot;vp8, vorbis\&quot;&quot;,
                  &quot;name&quot;: &quot;A wireworld computer! (small)&quot;,
                  &quot;width&quot;: 640,
                  &quot;height&quot;: 480},
                 {&quot;type&quot;: &quot;Link&quot;,
                  &quot;href&quot;: &quot;https://chatty.example/media/6e69f564/wireworld-large.webm&quot;,
                  &quot;mediaType&quot;: &quot;video/webm; codecs=\&quot;vp8, vorbis\&quot;&quot;,
                  &quot;name&quot;: &quot;A wireworld computer! (large)&quot;,
                  &quot;width&quot;: 1280,
                  &quot;height&quot;: 720},
               &quot;name&quot;: &quot;A wireworld computer!&quot;,
               &quot;attributedTo&quot;: &quot;https://chatty.example/ben/&quot;,
               &quot;to&quot;: [&quot;https://chatty.example/ben/collections/followers/&quot;,
                      &quot;https://www.w3.org/ns/activitystreams#Public&quot;],
               &quot;summary&quot;: &quot;&lt;p&gt;My friend Conway and I went over to our friend
                              Silverman's place and saw the wireworld computer
                              he's been constructing.  Pretty crazy!&lt;/p&gt;
                           &lt;p&gt;Tomorrow we're going over to our friend Langton's
                              place and see that ant farm he's been working
                              on...&lt;/p&gt;&quot;}}
          </pre>