From 9bdeb8a8853fe709b7ef0a5495f134a20018cefc Mon Sep 17 00:00:00 2001
From: Michael Dale <dale@users.mediawiki.org>
Date: Tue, 28 Jul 2009 17:52:09 +0000
Subject: [PATCH] improved upload api documentation

---
 includes/api/ApiUpload.php | 61 +++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 21 deletions(-)

diff --git a/includes/api/ApiUpload.php b/includes/api/ApiUpload.php
index 89dd1bec5c..62ff21aa72 100644
--- a/includes/api/ApiUpload.php
+++ b/includes/api/ApiUpload.php
@@ -289,21 +289,21 @@ class ApiUpload extends ApiBase {
 	public function getAllowedParams() {
 		return array(
 			'filename' => null,
-			'file' => null,
-			'chunk' => null,
-			'url' => null,
-			'token' => null,
-			'enablechunks' => null,
 			'comment' => array(
 				ApiBase::PARAM_DFLT => ''
 			),
-			'asyncdownload' => false,
+			'token' => null,
 			'watch' => false,
 			'ignorewarnings' => false,
+			'file' => null,
+			'enablechunks' => null,
+			'chunksessionkey' => null,
+			'chunk' => null,
 			'done' => false,
-			'sessionkey' => null,
+			'url' => null,
+			'asyncdownload' => false,
 			'httpstatus' => false,
-			'chunksessionkey' => null,
+			'sessionkey' => null,
 			'internalhttpsession' => null,
 		);
 	}
@@ -311,32 +311,51 @@ class ApiUpload extends ApiBase {
 	public function getParamDescription() {
 		return array(
 			'filename' => 'Target filename',
-			'file' => 'File contents',
-			'chunk'=> 'Chunk File Contents',
-			'url' => 'Url to upload from',
-			'comment' => 'Upload comment or initial page text',
-			'token' => 'Edit token. You can get one of these through prop=info (this helps avoid remote ajax upload requests with your credentials)',
-			'enablechunks' => 'Boolean If we are in chunk mode; accepts many small file POSTs',
-			'asyncdownload' => 'If we should download the url asyncrously usefull for large http downloads (returns a upload session key to get status updates in subquent calls)',
+			'token' => 'Edit token. You can get one of these through prop=info',
+			'comment' => 'Upload comment. Also used as the initial page text for new files',
 			'watch' => 'Watch the page',
 			'ignorewarnings' => 'Ignore any warnings',
-			'done'	=> 'When used with "chunks", Is sent to notify the api The last chunk is being uploaded.',
-			'sessionkey' => 'Session key in case there were any warnings.',
-			'httpstatus' => 'When set to true, will return the status of a given sessionKey (used for progress meters)',
+			'file' => 'File contents',
+			'enablechunks' => 'Set to use chunk mode; see http://firefogg.org/dev/chunk_post.html for protocol',
 			'chunksessionkey' => 'Used to sync uploading of chunks',
-			'internalhttpsession' => 'Used internally for http session downloads',
+			'chunk' => 'Chunk contents',
+			'done' => 'Set when the last chunk is being uploaded',
+			'url' => 'Url to fetch the file from',
+			'asyncdownload' => 'Set to download the url asynchronously. Useful for large files that will take more than php max_execution_time to download',
+			'httpstatus' => 'Set to return the status of an asynchronous upload (specify the key in sessionkey)',
+			'sessionkey' => array(
+				'Session key returned by a previous upload that failed due to warnings, or',
+				'(with httpstatus) The upload_session_key of an asynchronous upload',
+			),
+			'internalhttpsession' => 'Used internally',
 		);
 	}
 
 	public function getDescription() {
 		return array(
-			'Upload a file'
+			'Upload a file, or get the status of pending uploads. Several methods are available:',
+			' * Upload file contents directly, using the "file" parameter',
+			' * Upload a file in chunks, using the "enablechunks", "chunk", and "chunksessionkey", and "done" parameters',
+			' * Have the MediaWiki server fetch a file from a URL, using the "url" and "asyncdownload" parameters',
+			' * Retrieve the status of an asynchronous upload, using the "httpstatus" and "sessionkey" parameters',
+			' * Complete an earlier upload that failed due to warnings, using the "sessionkey" parameter',
+			'Note that the HTTP POST must be done as a file upload (i.e. using multipart/form-data) when',
+			'sending the "file" or "chunk" parameters. Note also that queries using session keys must be',
+			'done in the same login session as the query that originally returned the key (i.e. do not',
+			'log out and then log back in). Also you must get and send an edit token before doing any upload stuff.'
 		);
 	}
 
 	protected function getExamples() {
 		return array(
-			'api.php?action=upload&filename=Wiki.png&url=http%3A//upload.wikimedia.org/wikipedia/en/b/bc/Wiki.png&ignorewarnings'
+			'Upload from a URL:',
+			'    api.php?action=upload&filename=Wiki.png&url=http%3A//upload.wikimedia.org/wikipedia/en/b/bc/Wiki.png',
+			'Get the status of an asynchronous upload:',
+			'    api.php?action=upload&filename=Wiki.png&httpstatus=1&sessionkey=upload_session_key',
+			'Complete an upload that failed due to warnings:',
+			'    api.php?action=upload&filename=Wiki.png&sessionkey=sessionkey&ignorewarnings=1',
+			'Begin a chunked upload:',
+			'    api.php?action=upload&filename=Wiki.png&enablechunks=1'
 		);
 	}
 
-- 
2.20.1