Changes

understand the differences between the old and new API.

First of all, launch the [[Startup#BaseX HTTP Server|BaseX HTTP Server]], which will itself start an instance of the [http://jetty.codehaus.org/jetty/ Jetty WebServer], which listens to the default port <code>8984</code> by default (check out the additional [[Startup Options#BaseX HTTP Server|command-line options]]).

Some alternatives for using REST are listed in the [[#Usage Examples|Usage Examples]].

The root URL lists all available databases. The following examples assume that

If a resource is not found, an HTTP response will be generated with <code>404</code> as status code.

GET and POST requests support the following '''operations''':

* '''Get''':<br/>This is the default operation for the GET operation (it is not possible to use this operation in a POST request). It returns a list of all databases, the resources of a database or the addressed resource. If a resource with content type <code>application/xquery</code> is addressed, it will be evaluated first, and the result will be returned.

Additionally, the following '''parameters''' can be applied to the operations:

While '''Options''' can be specified for all operations, the remaining parameters will only make sense for '''Query''' and '''Run'''.

If the GET method is used, all query parameters are directly specified within the URL.

* The last example includes an to disallow [[Options#XQUERY3|XQuery 3.0]] expressions:<br/><code>http://localhost:8984/rest?query=12345&xquery3=false</code>

The body of a POST request is interpreted as XML fragment, which specifies the

</pre>

The PUT method is used to create new databases, or to add or update existing database resources:

could not be completed).

The DELETE method is used to delete databases or resources within a database.

<code>200</code> (OK) will be sent in all other cases.

All query parameters that have not been processed before will be treated as variable assignments:

Variables can also be explicitly prefixed with a dollar sign (<code>$</code>); this way, those variables can be bound as well that would otherwise be interpreted in a different way (e.g.: <code>$method</code>).

If <code>query</code> or <code>run</code> is used as operation, external variables can be specified via the <code><variable/></code> element:

</pre>

By default, the HTTP server is started with no predefined user. Users and passwords can be sent via [http://en.wikipedia.org/wiki/Basic_access_authentication HTTP basic authentication] with each HTTP request. As alternative, users and passwords can also be stored server-side in the "org.basex.user" and "org.basex.password" system properties before the HTTP server is started, or specified as [[Startup Options#BaseX HTTP Server|command-line arguments]].

: <code>http://admin:admin@localhost:8984/rest/factbook</code>

As the content type of a REST response cannot be dynamically determined in all cases, it can be manually adjusted by the user. The final content type of a REST response is chosen in several steps:

# By default, the content type of a response depends on the chosen operation:

# The default content type is overwritten if a [[Serialization|serialization method]] is specified, either as [[#Query Parameters|query parameter]] or within the XQuery expression. The following methods are available:

# The content type is overwritten in any case if a specific [[Serialization|media-type]] is chosen, again as query parameter or within the query.

:<code>http://localhost:8984/rest?query=%3Ca/%3E</code><br/><code>http://localhost:8984/rest?query=%3Ca/%3E&method=xml</code><br/><code>http://localhost:8984/rest?query=%3Ca/%3E&media-type=application/xml</code>

Most programming languages offer libraries to communicate with HTTP servers.

[[RESTGet|GET]], [[RESTPost|POST]], [[RESTPut|PUT]], [[RESTDelete|DELETE]].

Tools such as the Linux commands [http://www.gnu.org/s/wget/ Wget] or [http://curl.haxx.se/ cURL] exist to

:<code>curl -i -X DELETE "admin:admin@localhost:8984/rest/factbook"</code>

* Added: {{Mono|options}} parameter for specifying database options