Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
First of all, please launch a '''HTTP Server''' instance of BaseX: please run the <code>basexhttp</code> script, or double click on the '''BaseX Server (Start)''' start icon in Windows. [[Startup#BaseX HTTP Server|Follow this link]] for some more information (or check out the additional [[Startup Options#BaseX HTTP Server|command-line options]]).
Using If the GETmethod is used, all query parameters can be are directly specified within the URL.
The In the next request chooses , <code>US-ASCII</code> is chosen as output encoding , and opens the database is opened within the XQuery expression:
The POST method offers two different operations:
====Add New Resources====
By default, the HTTP request body will be added as new XML document to the specified
database. For example, if a document is sent as body of the POST request to the URL
<code>localhost:8984/rest/DB/file.xml</code>, the document will be added to the
<code>DB</code> database, and the 201 (Created) status code will be returned to
confirm that everything went alright.
====Execute Queries & Commands====The body of a POST request is interpreted as XML fragment, which specifies theoperation to perform. The body must conform to a given [[REST POST Schema]].
If <code>application/query+xml</code> is chosen as content type, the HTTP requestbody is interpreted as query. The body must conform to the [[REST POST Schema]].; Examples
;Example* <code>localhost:8984/rest/XMark</code>: <br/>A new database with the name <b>XMark</b> is created if . If XML input is sent in the HTTP body, the URL resulting databasse document will be called <b>XMark.xml</b>.* <code>localhost:8984/rest/XMark/one.xml</code> is sent via : The contents of the HTTP body will be taken as input for the document <b>PUTone.xml</b>, followed by the input XML file which will be stored in the HTTP body. The document will have the same name as the <b>XMark</b> database.
If the process was successful, a An HTTP response with status code <code>201</code> (CREATED) is sent backif the operation was successful.Otherwise, the server will reply with <code>404</code> will (if a specifieddatabase was not found) or <code>400</code> (if the operationcould not be sentcompleted).
VariablesParameters:
;GET :<code>curl -i "bobhttp:alice//admin:admin@localhost:8984/rest/factbook"</code>
Next, tools Tools such as the Linux commandcommands [http://www.gnu.org/s/wget/ Wget] or [http://curl.haxx.se/ cURL] exist to
no edit summary
interact with the database.
The REST implementation has formerly beenbased on [http://jax-rx.sourceforge.net JAX-RX], an interface a generic layer toprovide unified access to XML databases and resources. With<font color='orangered'>Version 6.8</font>, it has been replaced with a nativeRESTREST implementation that allows a much closer integration with theXQuery, WebDAV, and other features of BaseX. If you have worked with JAX-RX before, please take some time tounderstand the differences between the old and new API.
==Starting HTTP Server==
First of all, please launch a '''HTTP Server''' instance of BaseX: run the <code>basexhttp</code> script, or double click on the '''BaseX Server (Start)''' start icon in Windows. [[Startup#BaseX HTTP Server|Follow this link]] for some more information (or check out the additional [[Startup Options#BaseX HTTP Server|command-line options]]). Most browsers can be used to directly display the results of REST requests. Some more alternatives how to use REST are listed in the [[#Usage Examples|Usage Examples]] Paragraphbelow.
==URL Architecture==
</pre>
The contents of a database can be accessed retrieved by adding the an empty <b>query</b> parameter to the path:
:<code>[http://admin:admin@localhost:8984/rest/factbook?query http://admin:admin@localhost:8984/rest/factbook?query]</code>
If a resource is not found, an HTTP response will be generated with <code>404</code> as status code.
===Query ParametersOperations===
GET and POST requests can be extended with a number of parameters.Only one of support the following three '''operations''' can be specified:
* <code>query</code>:<br/>Evaluates an XPath/XQuery expression.<br/>If a database or database path is specified in the URL, it is used as initial query context.
* <code>run</code>:<br/>Runs a query file located on the server.<br/>The query directory is defined by the <code>[[Options (Snapshot)#HTTPPATH|HTTPPATH]]</code> option.
* <code>command</code>:<br/>Executes a [[Commands|database command]].
===Parameters===
The following parameters can be applied to the <code>query</code> and <code>run</code> operations:
* '''VariablesSerialization'''::<br/>All query parameters prefixed with a dollar sign (<code>$</code>) will be treated as external variables. The parameter name and value will be bound to the query before it is evaluated.* '''[[Serialization]]''':<br/>All serialization parameters known to BaseX can be specified as query parameters. Parameters that are specified within a query will be interpreted by the REST server before the output is generated.* '''Variables''':<br/>External variables can be ''bound'' before a query is evaluated ([[REST#Assigning Variables|see below]] for more).
* <code>context</code>:<br/>May be used to provide an initial context node.
* <code>wrap</code>:<br/>Wraps the results in XML elements (default: <code>no</code>).
===GET Requests===
The following example prints the city names from the ''factbook'' database:
:<code>[http://admin:admin@localhost:8984/rest/factbook?query=//city/name http://admin:admin@localhost:8984/rest/factbook?query=//city/name]</code>
:<code>[http://admin:admin@localhost:8984/rest?query=distinct-values(db:open('factbook')//religions)&encoding=US-ASCII http://admin:admin@localhost:8984/rest?query=distinct-values(db:open('factbook')//religions)&encoding=US-ASCII]</code>
The next URL turns on XML wrapping and lists all database users registered in that are known to BaseX:
:<code>[http://admin:admin@localhost:8984/rest?command=show+users http://admin:admin@localhost:8984/rest?command=show+users]</code>
===POST Requests===
The output of the following query returns the first five first city names of the <b>factbook</b> database:
<pre class="brush:xml">
<query xmlns="http://www.basex.org/rest">
</pre>
The second query returns the string lengths of all text nodes, which are found in the node that has been specified as initial context node:
<pre class="brush:xml">
<rest:query xmlns:rest="http://www.basex.org/rest">
</pre>
The following POST request prints returns the registered database users encoded in the specified <code>ISO-8859-1</code> encoding:
<pre class="brush:xml">
<command xmlns="http://www.basex.org/rest">
===PUT Requests===
The PUT method can be is used to create new databases, or to add or update existing database resources: * a new database is created if the URL only specifies the ''name of a database''. If the request body contains XML, a single document is created, adopting the name of the database.* a document is added to the database if the URL contains a ''database resourcepath''. If the addressed document already exists, it is replaced by the new XML input.
;Usage: Use <b>PUT</b> to send the URL and upload the input XML document.Examples
===DELETE Requests===
The DELETE method can be applied is used to delete single databases or resourceswithin a database.<br/>
;UsageExample* <code>localhost: Use 8984/rest/factbook<b/code>DELETE:<br/b> to send the URL pointing to the database or resource to be deleted. ;Example: The <b>factbook</b> database is deleted via * <code>localhost:8984/rest/XMark/tmp/</code>:<br/>All resources of the <b>DELETEXMark</b> method and database are deleted that reside in the URL <codeb>localhost:8984/rest/factbooktmp</codeb>path. If deletion was successful, the The HTTP status code <code>200404</code> (OK) will be sentis returned if no database is specified.If not, <code>404200</code> is returned(OK) will be sent in all other cases.
==Assigning Variables==
===GET Requests===
Query parameters prefixed with a dollar sign (<code>$</code>) will be handled as external variables:
</pre>
:Assign the variable with: <code>&$x=21</code>
Complete request (compact notation, omitting the explicit optional variable declarationsdeclaration)::<code>http://admin:admin@localhost:8984/rest?query=$x&$x=21</code>
===POST Requests===
Using POST, the <code><variable/></code> element is used to bind an specify external variable to a queryvariables:
<pre class="brush:xml">
==User Management==
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 access authentication] with each HTTP request. As an alternative, users and passwords can also be specified as command-line arguments or via stored in the "user.basex.user" and "user.basex.password" system properties before the HTTP server is started,or specified as [[Startup Options#BaseX HTTP Server|command-line arguments]].
With some most browsers and with cURL, you can send specify the user name and password with each HTTP request within the request string as plain text, using the format <code>USER:PASSWORD@URL</code>. An example:
==Content Type==
As the correct result content type of a REST response cannot always be dynamically determinedin all cases, the user it can be manually adjust adjusted by the content typeuser. 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:
===Java===
Most programming languages offer libraries to communicate with HTTP servers.
The following example demonstrates how easy it is to perform a DELETE request with Java.
===Command Line===
perform HTTP requests (try copy & paste):
