API:Import

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png This page is part of the MediaWiki API documentation.
Language: English  • 日本語
MediaWiki API

Quick overview:

v · d · e


MediaWiki version: 1.15

Token[edit | edit source]

To import pages, an import token is required. This token is equal to the edit token and the same for all pages, but changes at every login. Import tokens can be obtained via action=tokens with type=import (MW 1.20+), or by using the following method:

Obtaining an import token

Importing pages[edit | edit source]

Pages can be imported with action=import, either by uploading an XML file or by specifying a page from another wiki (also known as transwikiing).

Parameters[edit | edit source]

Parameters marked with (upload) are only used when importing an uploaded XML file. Similarly, parameters marked with (interwiki) are only used when importing from another wiki (transwiki).

  • token: The token obtained in the previous request. Take care to urlencode the trailing +\ as %2B%5C.
  • summary: Summary for the import log (optional)
  • xml: Uploaded XML file (upload)
  • interwikisource: Wiki to import from (interwiki)
    • The possible values for this parameter differ per wiki, see $wgImportSources. If the list of possible values for this parameter is empty, interwiki imports are disabled
  • interwikipage: Title of the page to import (interwiki)
  • fullhistory: If set, import the full history rather than just the current revision (interwiki)
  • namespace: Namespace to import to. If not set, don't change the page's namespace (interwiki)
  • templates: Import all included templates as well (interwiki)

Example[edit | edit source]

Note: In these examples, all parameters are passed in a GET request just for the sake of simplicity. However, action=import requires POST requests; GET requests will cause an error.

Interwiki[edit | edit source]

Import meta:Special:MyLanguage/Help:ParserFunctions to the Manual namespace (namespace 100) with full history

XML file[edit | edit source]

Import XML dump dump.xml (from Special:Export) to the Manual namespace (namespace 100)

When uploading a file, you need to use multipart/form-data as Content-Type or enctype, application/x-www-form-urlencoded will not work. The parameter xml is not a file name, but the actual content of a file.

Ruby source code example using httpclient (assumes login cookies are already in @headers)

 res = HTTPClient.post(@api_url, {
                              :action => 'import',
                              :xml => File.open("dump.xml"),
                              :token => token,
                              :format => 'xml'}, @headers)
FormData[edit | edit source]

If the result says "no file" it is expecting a file in a POST body. You can easily POST using FormData.

To quote from /api.php

    xml      - Uploaded XML file
               Must be posted as a file upload using multipart/form-data
JavaScript example[edit | edit source]

For simplicity, the following code is reading the XML from a textarea and makes use of MediaWiki's JavaScript includes:

 var apiUrl = mw.util.wikiScript( 'api' );
 var onreadystatechange = function() {
	if ( 4 !== this.readyState ) return;
	if ( 200 === this.status ) {
	  console.log( this.response );
	}
 };
 
 function continueWithToken ( token ) {
	  var fd = new FormData();
	  var xhr = new XMLHttpRequest();
	  // First argument is an array!
	  var bXml = new Blob( [$( 'textarea' ).val()], {
				 type: 'text/xml'
			} );
	  fd.append( 'format', 'json' );
	  fd.append( 'action', 'import' );
	  // Third parameter is not required but
	  // You're likely on the safe side using it
	  fd.append( 'xml', bXml, 'file.xml' );
	  fd.append( 'token', token );
 
	  xhr.onreadystatechange = onreadystatechange;
	  xhr.open( 'POST', apiUrl );
	  xhr.send( fd );
 }
 
 $.get( apiUrl, {
	  format: 'json',
	  type: 'import',
	  action: 'tokens'
 } ).done( function(r) {
	  var token = r.tokens.importtoken;
	  continueWithToken( token );
 } );

This is just a minimal implementation. Do not forget error-handling. If you have the exports as files for upload and want to make it working in older browsers not sufficiently supporting Blobs and FormData, just build a HTML form. The form's target could be an iframe so you can read the response from it without exposing the blank API result page to your users.

Expected response[edit | edit source]
{"import":[{"ns":0,"title":"Main Page2","revisions":1}]}
Raw request resulting[edit | edit source]

The request that is composed by the client and sent to the server for reference. Note the file's in a POST body.

POST http://localhost/api.php HTTP/1.1
Host: localhost
User-Agent: <ua string>
Accept-Language: de,en-US;q=0.7,en;q=0.3
Accept-Encoding: gzip, deflate
Referer: http://localhost/index.php?title=Special:Export&action=submit
Content-Length: 3231
Content-Type: multipart/form-data; boundary=---------------------768648126486
Cookie: <redacted>; mwdbUserID=1; mwdbUserName=Rillke
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

-----------------------768648126486
Content-Disposition: form-data; name="format"

json
-----------------------768648126486
Content-Disposition: form-data; name="action"

import
-----------------------768648126486
Content-Disposition: form-data; name="xml"; filename="file.xml"
Content-Type: text/xml

<mediawiki ...schemas... version="0.8" xml:lang="en">
<siteinfo>
  <sitename>Sample Wiki</sitename>
<!-- .... -->
</mediawiki>
-----------------------768648126486
Content-Disposition: form-data; name="token"

XX39e9fd22a9de7675c71eadcfd2XXXX+\
-----------------------768648126486--
"Missing boundary in multipart/form-data POST data" error?

This is because you sent it url-encoded but claimed it would be multipart/form-data? MediaWiki is looking for a boundary in the header but cannot find it.

Possible errors[edit | edit source]

All errors are formatted as:

<error code="code" info="info">
Code Info
notoken The token parameter must be set
cantimport You don't have permission to import pages
cantimport-upload You don't have permission to import uploaded pages
nointerwikipage The interwikipage parameter must be set
nofile You didn't upload a file
filetoobig The file you uploaded is bigger than the maximum upload size
partialupload The file was only partially uploaded
notempdir The temporary upload directory is missing
Note: This generally means the server is broken or misconfigured
cantopenfile Couldn't open the uploaded file
Note: This generally means the server is broken or misconfigured
badinterwiki Invalid interwiki title specified
import-unknownerror Unknown error on import: "error"

See also[edit | edit source]