Changes

This page is part of the [[Getting Started]] Section. It describes how BaseX provides access can be used to stored database resources both provide simple APIs and to the XQuery engine via build complex web applications. The following three HTTP services are available: * [[REST]] offers a straightforward RESTful API for accessing database resources via URLs, * [[RESTXQ]] allows you to write more complex APIs and full web applications with XQuery, and* [[WebDAV]] servicesgives access to databases via the file system.  This article describes different ways of deploying and configuring these services. The services can be deployed as follows: * as standalone application, by running the [[Startup#HTTP Server|BaseX HTTP Server]],* as web servlet in three different waysa [[#Servlet Container|Servlet Container]], and* as web servlet, using [[#Maven|Maven]]. Authentication: * If a user is defined in the <code>web.xml</code> file via the key <code>org.basex.user</code>, no password must be specified.* If the <code>admin</code> user is specified for an API, all features will be available without restriction.* Predefined authentication methods and default users cannot be overwritten by client.

In order to deploy BaseX HTTP Services in a servlet container, you may can download the WAR distribution of BaseX from the [http://basex.org/download download site] , or compile it via by calling <code>mvn compile war:war</code> in the <code>basex-api</code> packagedirectory. The WAR file can then be deployed following the instructions of the corresponding servlet container ([http://docswww.codehauseclipse.org/displayjetty/JETTYdocumentation/WebAppDeployer current/quickstart-deploying-webapps.html jetty], [http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html tomcat], etc.).

Configuring You can configure the port, context path, etc. can be done by following the corresponding instructions of the used corresponding servlet container. This is needed if you want to replace the default URL path (e.g. http://localhost:8080/rest) with a custom one (e.g. http://localhost:80808984/BaseX711basex/rest).

If run on a you use Jetty (which is the default HTTP server of BaseX), the server you may use a configuration is available via the {{Code|jetty.xml}} file for detailed server configuration. You can e.g. enable SSL connections or Jetty logging. Place , which is stored in the {{Code|jetty.xmlWEB-INF}} right directory next to the {{Code|web.xml}}. For detailed configuration refer to the [http://wikiwww.eclipse.org/Jetty/Reference/jetty.xml Jetty Documentation]. A sample [https://github.comdocumentation/BaseXdbcurrent/basexjetty-api/blob/master/src/main/webapp/WEBxml-INF/jettyconfig.xml jetty.xmlhtml Jetty Documentation] is placed in the basex-api package.

To run on [http://tomcat.apache.org/ Apache Tomcat], start the tomcat Tomcat server and add any <code>*.WARwar</code> distribution to deploy using via the Tomcat web interface (by . By default located at , the interface is accessible via http://localhost:8080/manager/html/ ).

All database options can be specified in the {{Code|web.xml}} file by prefixing the key . They need to be defined as context parameters and prefixed with {{Code|org.basex.}}.The most important options for the web application context are as follows:

|<code>[[Options#USER|USER]]</code>

| User name. By default, the {{Code|admin}} user is specified. If no a user is specified, the no credentials must be passed on by the client. Please check by yourself if it is safe to store your credentials in plain text.

|<code>[[Options#USERHTTPLOCAL|PASSWORDHTTPLOCAL]]</code>|{{Code|adminfalse}}| Login dataOperation mode. By default, a database server instance will be started, as soon as the first HTTP service is called. The database server can be disabled by setting this flag to {{Code|admintrue}} password is specified. If no password is specified, it must be passed on by the client. Please check by yourself if it is safe to store your credentials in plain text.

|<code>[[Options#HTTPLOCALRESTXQPATH|HTTPLOCALRESTXQPATH]]</code>|{{Code|false.}}|Operation modeRelative or absolute directory referencing the [[RESTXQ]] modules. By default, the servlets will work in client/server mode, and a database server instance will be started along with option points to the standard web server, which can also be addressed from other BaseX clients. If the flag is set to {{Code|true}}, all servlets will communicate with a local database context which is not accessible from outsideapplication directory.

|<code>[[Options#RESTXQPATHRESTPATH|RESTXQPATHRESTPATH]]</code>

|Relative or absolute directory referencing queries and command-scripts that can be invoked via the [[RESTXQREST#GET_Requests|run operation]] directoryof REST. By default, all RESTXQ modules are located in the option points to the standard web application directory.|-|<code>[[Options#AUTHMETHOD|AUTHMETHOD]]</code>|{{Code|Basic}}|The default authentication method proposed by the server. The available methods are {{Code|Basic}} and {{Code|Digest}}.

Context parameters can be requested from XQuery via [[Process_Module#proc:property-names|proc:property-names]] and [[Process_Module#proc:property|proc:property]]. How to set these options in the {{Code|web.xml}} of the BaseX web application is specific to the servlet container. For example, in Jetty it is can be done by [httpshttp://wikiwww.eclipse.org/Jettyjetty/documentation/Referencecurrent/override-web-xml.xml html overriding the web.xml] file. Another option is to directly edit the {{Code|WEB-INF/web.xml}} file in the WAR archive (WAR files are simple ZIP files). Refer to the sample [https://github.com/BaseXdb/basex-api/blob/master/basex-api/src/main/webapp/WEB-INF/web.xml web.xml] of the basex-api package.

Different credentials can be assigned to each HTTP the REST and WebDAV service by specifying local init parameters. In the following example, the global credentials are overwritten and reset an alternative user is specified for the REST service:

<param-value/> </init-param> <init-param> <paramrest-name>org.basex.passworduser</param-name> <param-value/>

| {{Code|http://[host]:[port]/[servlet_context_path]/static}}<br/>Before: {{Code|http://[host]:[port]/[servlet_context_path]}}

| {{Code|http://[host]:[port]/[servlet_context_path]}}<br/>Before: {{Code|http://[host]:[port]/[servlet_context_path]/restxq}}<br/>

Checkout Check out the BaseX sources via [[Developing with Eclipse|Eclipse]] or [[Git]]. Execute <code>mvn install</code> in the <code>basex</code> main project folder directory and then <code>mvn install jetty:run</code> in the <code>basex-api</code> project foldersub-directory. This will start a Jetty instance in which the servlets will be deployed.

The same options as in the case of deployment apply in a servlet container apply. In this case, however, there is no WAR archive. Instead, Jetty looks up all files in the directory <code>[https://github.com/BaseXdb/basex/tree/master/basex-api/src/main/webapp basex-api/src/main/webapp]</code>. Jetty and servlet options can be configured in the {{Code|jetty.xml}} and {{Code|web.xml}} files as described above in the [[#Configuration|Servlet Container Configuration]]. The Jetty stop port can be changed in the [http://docs.codehaus.org/display/JETTY/Maven+Jetty+Plugin Maven Jetty Plugin] sesion in the {{Code|pom.xml}} file.

If By default, RESTXQ uses the HTTP server is started with no pre-defined credentialsadmin user, users whereas the REST and passwords can be sent via [http://en.wikipedia.org/wiki/Basic_access_authentication HTTP basic WebDAV services require client-side authentication] with each HTTP request. Login data A default user can be stored server-side in the <code>web.xml</code> file, or specified as via [[Command-Line Options#BaseX HTTP Server|command-line arguments]]. In the <code>web.xml</code> file, both a global and a servlet-specific user can be added (see above).

For multiIf the HTTP server is started with no pre-defined user access, or a changed {{Code|admin}} password, you may place the credentials must be passed on by the client via [http://en.wikipedia.org/wiki/Basic_access_authentication Basic Authentication] or [Configuration#Configuration_Files|http://en.basexperm]wikipedia.org/wiki/Digest_authentication Digest Authentication] configuration file in (depending on the server root. More details are found in the [[User Management]] articlesetting).

With cURL, internet browsers, and most browsersother tools, you can specify the user name and password with each HTTP request basic authentication credentials within the request string as plain text, using the format <code>USER:PASSWORD@URL</code>. An example: