From BaseX Documentation
This page is part of the Getting Started Section. It describes how BaseX can be used to both provide simple APIs and 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 gives 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 BaseX HTTP Server,
- as web servlet in a Servlet Container, and
- as web servlet, using Maven.
- If a user is defined in the
web.xmlfile via the key
org.basex.user, no password must be specified.
- If the
adminuser 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 can download the WAR distribution of BaseX from the download site, or compile it by calling
mvn compile war:war in the
basex-api directory. The WAR file can then be deployed following the instructions of the corresponding servlet container (jetty, tomcat, etc.).
You can configure the port, context path, etc. by following the instructions of the 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:8984/basex/rest).
If you use Jetty (which is the default HTTP server of BaseX), the server configuration is available via the
jetty.xml file, which is stored in the
WEB-INF directory next to the
web.xml. For detailed configuration refer to the Jetty Documentation.
To run on Apache Tomcat, start the Tomcat server and add any
*.war distribution to deploy via the Tomcat web interface. By default, the interface is accessible via http://localhost:8080/manager/html/.
All database options can be specified in the
web.xml file. They need to be defined as context parameters and prefixed with
org.basex.. The most important options for the web application context are as follows:
|If a user is specified, no credentials must be passed on by the client.|
|Operation 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 |
|Relative or absolute directory referencing the RESTXQ modules. By default, the option points to the standard web application directory.|
|Relative or absolute directory referencing queries and command-scripts that can be invoked via the run operation of REST. By default, the option points to the standard web application directory.|
|The default authentication method proposed by the server. The available methods are |
Path options may contain an absolute or relative path. If a relative path is specified, its root will be the servlet (
<context-param> <param-name>org.basex.dbpath</param-name> <!-- will be rewritten to ..../webapp/WEB-INF/data --> <param-value>WEB-INF/data</param-value> </context-param> <context-param> <param-name>org.basex.repopath</param-name> <!-- will be kept as is --> <param-value>f:/basex/repository</param-value> </context-param>
Context parameters can be requested from XQuery via proc:property-names and proc:property. How to set these options is specific to the servlet container. For example, in Jetty it can be done by overriding the web.xml file. Another option is to directly edit the
WEB-INF/web.xml file in the WAR archive (WAR files are simple ZIP files). Refer to the sample web.xml of the basex-api package.
Different credentials can be assigned to the REST and WebDAV service by specifying local init parameters. In the following example, an alternative user is specified for the REST service:
<servlet> <servlet-name>REST</servlet-name> <servlet-class>org.basex.http.rest.RESTServlet</servlet-class> <init-param> <param-name>org.basex.user</param-name> <param-value>rest-user</param-value> </init-param> </servlet>
To enable or disable one of the provided services, the corresponding servlet entry in the
web.xml file needs to be removed/commented. The default URL paths are listed in the following table:
|RESTXQ|| ||Create XQuery web services and applications.|
|REST|| ||Access XML database and its resources.|
|WebDAV|| ||Access databases via the filesystem.|
Check out the BaseX sources via Eclipse or Git. Execute
mvn install in the main project directory and then
mvn install jetty:run in the
basex-api sub-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. In this case, however, there is no WAR archive. Instead, Jetty looks up all files in the directory
basex-api/src/main/webapp. Jetty and servlet options can be configured in the
web.xml files as described above in the Servlet Container Configuration. The Jetty stop port can be changed in the Maven Jetty Plugin sesion in the
By default, RESTXQ uses the admin user, whereas the REST and WebDAV services require client-side authentication.
A default user can be specified via command-line arguments. In the
web.xml file, both a global and a servlet-specific user can be added (see above).
With cURL, internet browsers, and other tools, you can specify basic authentication credentials within the request string as plain text, using the format
USER:PASSWORD@URL. An example:
Users are specified in a
users.xml file, which is stored in the database directory (see User Management for more information).
- Version 8.6
- Updated: Authentication readded to RESTXQ.
- Updated: No password must be specified in the
- Updated: Server-side user and authentication method is now enforced (cannot be overwritten by client).
- Version 8.0
- Added: digest authentication
- Updated: user management
- Updated: default user/password disabled in web.xml
- Version 7.7
- Added: service-specific permissions
- Version 7.5
jetty.xml: configuration for Jetty Server
- Version 7.3
clientmode replaced with
- Version 7.2
- Web Application concept revised