====== Remote API ======

DokuWiki provides a Remote API which can be used to access/interact with your wiki from other applications. 


===== Enabling the API =====

The API is disabled by default and needs to be enabled by an administrator before it can be used.

  - Enable the [[config:remote]] option in the configuration manager
  - Configure a list of comma separated user and/or groups that are allowed to access the API in the [[config:remoteuser]] option
  - If you plan to have your API used from client side JavaScript applications you may want to configure the [[wp>CORS]] header settings in the [[config:remotecors]] option.

===== Accessing the API =====

DokuWiki offers two protocols to interact with the Remote API. Refer to their respective documentation pages to learn more:

  - [[xmlrpc|XML-RPC]]
  - [[jsonrpc|JSON-RPC]]

The latter is the recommended, more modern interface.

===== Authentication =====

Nearly all call need to be made authenticated as a valid DokuWiki user. The preferred method for API access is Token Auth. Please refer to [[Authentication]] to learn more.

===== Available API Calls =====

API calls are divided into two namespaces:

  * ''core.*'' are calls provided by the DokuWiki core itself
  * ''plugin.<pluginname>.*'' are calls provided by [[remote plugins]], this includes calls provided by some of the bundled plugins

Please refer to the **[[https://www.dokuwiki.org/lib/exe/openapi.php|API Explorer]]** to read the documentation of available calls.

You can also open the API Explorer on your own wiki instance. This way you will see all ''plugin.*'' calls available at your instance. To do so open the following URL in your web browser:

  * ''%%https://yourwiki/dokuwiki/lib/exe/openapi.php%%''

Of course replace ''yourwiki/dokuwiki'' with the server and path your wiki is available at.

===== Error Codes =====

Any errors occurring in an API call will be signaled by errors with an appropriate error code.

Error codes are meant to be unique per type of error and namespace. This means one specific error code will have the same meaning in any of the ''core.*'' calls, but might mean something different when returned by a ''plugin.<something>.*'' call.

  * Core error codes are listed in the API Explorer
  * Plugin error codes should be listed on their respective documentation page
  * API framework codes are listed below

==== API Frame work errors ====

Negative codes signal errors which occurred even before the call could be routed to a specific API call handler.

  * -32600 -> Invalid request. Not conforming to specification.
  * -32601 -> Requested method does not exist.
  * -32602 -> Wrong number of parameters or invalid method parameters.
  * -32603 -> Not authorized to call the requested method (No login or invalid login data was given).
  * -32604 -> Forbidden to call the requested method (but a valid login was given).
  * -32605 -> The API has not been enabled in the configuration
  * -32700 -> Parse Error. Request not well formed.
  * -32800 -> Recursive calls to system.multicall are forbidden.
  * -99999 -> Unknown server error.

===== Extending the API =====

Please refer to [[remote plugins]] to learn how to add calls to the API.

If you want to implement your own transport layer (REST, SOAP, gRPC, ...) you need to implement your endpoint (could be any file in a plugin) which instantiates the [[xref>\dokuwiki\Remote\Api]].

<code php>
<?php
// get the api
$remote = new dokuwiki\Remote\Api();

// Parse the incoming call
...

// call the business logic 
$result = $remote->call('core.getVersion');

// or with parameters
$result = $remote->call('core.deleteMedia', ['file'=>'anImage.jpg']);

// deliver the result
</code>

Best refer to the source of [[xref>inc/Remote/JsonRpcServer.php]] as an example starting point.