API:Edit - Uploading files

From MediaWiki.org

This page is part of the MediaWiki API documentation.

Language:

English

There are three methods of uploading files via the API:

1. Uploading a local file directly
2. Uploading a local file in chunks using Firefogg chunked upload protocol
3. Uploading a copy of a file elsewhere on the Web given by a URL

All of these methods require an account with the "upload" right.

[edit] Token

To upload files, a token is required. This token is identical to the edit token and is the same regardless of target filename, but changes at every login. Unlike other tokens, it cannot be obtained directly, so one must obtain and use an edit token instead.

Obtaining a token

<api>
  <query>
    <pages>
      <page
        pageid="1"
        ns="0"
        title="Foo"
        touched="2000-01-01T00:00:00Z"
        lastrevid="1"
        counter="0"
        length="0"
        edittoken="+\" 
      />
    </pages>
  </query>
</api>

[edit] Uploading

Parameters

• filename - Target filename
• comment - Upload comment. Also used as the initial page text for new files
• token - Edit token
• watch - Watch the page
• ignorewarnings - Ignore any warnings
• file - File contents
• enablechunks - Set to use chunk mode
• chunksessionkey - Used to sync uploading of chunks
• chunk - Chunk contents
• done - Set when the last chunk is being uploaded
• url - Url to fetch the file from
• asyncdownload - Set in conjunction with url to download the file asynchronously. Requires $wgEnableAsyncDownload = true in the wiki's local settings
• httpstatus - Set to return the status of an asynchronous upload (specify the key in sessionkey)
• sessionkey - Session key returned by a previous upload that failed due to warnings, or (with httpstatus) The upload_session_key of an asynchronous upload

[edit] Uploading directly

When uploading files directly, the request must use the POST method in "multipart/form-data" form, "application/x-www-form-urlencoded" will not work. The below is only a guide.

Uploading a text file

<api>
  <upload result="Success" filename="Test.txt">
    <imageinfo timestamp="2000-01-01T00:00:00Z" user="127.0.0.1" anon="" size="1000" width="0" height="0" url="http://localhost/images/3/35/Test.txt" descriptionurl="http://localhost/index.php/File:Test.txt" comment="" sha1="b8f32ebbf9512d8641d7e72c86614c2cee3e8108" metadata="" mime="text/plain" bitdepth="0" />
  </upload>
</api>

[edit] Chunked upload

See http://firefogg.org/dev/chunk_post.html for the relevant protocol. Note that responses will be in JSON format, regardless of the format specified in the request. Chunks must be sent in "multipart/form-data" form, "application/x-www-form-urlencoded" will not work. The below is only a guide.

Starting a chunked upload

{"uploadUrl":"http:\/\/localhost\/current\/api.php?action=upload&token=%2B%5C&format=json&enablechunks=true&chunksessionkey=12345"}

[edit] Uploading from URL

This requires $wgAllowCopyUploads = true in the wiki's local settings and an account with the upload_by_url user right. By default this is done synchronously, so downloading large files may exceed PHP's max_execution_time and fail. Asynchronous mode will return a session key that can then be used to query the upload status (see below). Asynchronous mode requires $wgEnableAsyncDownload = true in the wiki's local settings.

Upload from URL (synchronous)

<api>
  <upload result="Success" filename="Test.gif">
    <imageinfo timestamp="2009-10-30T05:06:43Z" user="Gurch" size="8558" width="276" height="110" url="http://localhost/images/e/ea/Test.gif" descriptionurl="http://localhost/index.php/File:Test.gif" comment="" sha1="fd852df5478eb7eb9410ee9101bb364adf487fb0" mime="image/gif" bitdepth="8">
      <metadata>
        <metadata name="frameCount" value="1" />
        <metadata name="looped" value="" />
        <metadata name="duration" value="0" />
      </metadata>
    </imageinfo>
  </upload>
</api>

Upload from URL (asynchronous)

<api>
  <upload upload_session_key="12345" />
</api>

[edit] Retrieving upload status

For asynchronous uploads using upload-by-url the initial response will include a session key; pass this with httpstatus parameter to fetch upload status. This session key does not remain valid across login sessions.

Retrieving upload status

<api>
  <upload upload_session_key="12345" loaded="0" content_length="8558" />
</api>