API:Upload
 |
This page is part of the MediaWiki API documentation. |
| Language: | English |
|---|
Quick overview:
- Quick start guide
- FAQ
- Formats
- Error reporting
- Restricting usage
- Authentication
- Queries
- Search suggestions
- Expanding templates and rendering
- Purging pages' caches
- Parameter information
- Changing wiki content
- Watchlist feed
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
| MediaWiki version: | 1.16 |
There are three methods of uploading files via the API:
- Uploading a local file directly
- Uploading a local file in chunks using Firefogg chunked upload protocol
- 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.
Contents |
[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 if text parameter not provided
- text - Initial page text for new files.
- token - Edit token
- watch - Watch the page
- ignorewarnings - Ignore any warnings
- file - File contents
- url - Url to fetch the file from
- 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 multipart/form-data as Content-Type or enctype, 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] 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>
[edit] Sample Raw Upload
Newlines are \r\n.
User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1) Content-Type: multipart/form-data; boundary=---------------------------8ce5ac3ab79ab2c Host: commons.wikimedia.org Cookie: <cookies> Content-Length: <proper content length> Connection: Keep-Alive -----------------------------8ce5ac3ab79ab2c Content-Disposition: form-data; name="action" Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit upload -----------------------------8ce5ac3ab79ab2c Content-Disposition: form-data; name="filename" Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apple.gif -----------------------------8ce5ac3ab79ab2c Content-Disposition: form-data; name="text" Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit text -----------------------------8ce5ac3ab79ab2c Content-Disposition: form-data; name="comment" Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit comment -----------------------------8ce5ac3ab79ab2c Content-Disposition: form-data; name="token" Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 0ff12678952302357892acc565412393+\ -----------------------------8ce5ac3ab79ab2c Content-Disposition: form-data; name="format" Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit xml -----------------------------8ce5ac3ab79ab2c Content-Disposition: form-data; name="file"; filename="Apple.gif" Content-Type: application/octet-stream; charset=UTF-8 Content-Transfer-Encoding: binary <Gif in binay> -----------------------------8ce5ac3ab79ab2c--
