Main Page » Getting Started » Web Application

Web Application

This page describes how BaseX can be used to both provide simple APIs and build complex web applications.

Startup

Run one of the basexhttp or basexhttp.bat Start Scripts.
If you have installed BaseX on Windows, click on the BaseX HTTP Server (Start) icon.

To shut down the server gracefully, run basexhttpstop or basexhttpstop.bat, attach the stop argument to the command call, or click on the BaseX HTTP Server (Stop) icon.

An instance of Jetty will be started, which listens to the port 8080 by default. After startup, you can access a plain HTML welcome page via http://localhost:8080. If the HTTPLOCAL option is disabled (see -L), the BaseX Database Server will be started in addition and can be addressed by Clients on port 1984.

basexhttp -c PASSWORD
BaseX [HTTP Server]
...
[main] INFO org.eclipse.jetty.util.log - org.eclipse.jetty.util.log.Slf4jLog
...
HTTP STOP Server was started (port: 8081).
HTTP Server was started (port: 8080).
Password: _

The Jetty logging level can be adjusted by adding the following properties to the start script:

-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog -D{classref}.LEVEL=DEBUG

Various Command-Line Options are available to simplify batch processing. The Start Script can be adjusted for individual purposes (e.g. if the default memory limit is too restrictive).

BaseX can also be deployed as web servlet in a servlet container, with Maven, or in a container:

Servlet Container

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:8080/api/rest).

If you use Jetty (which is the default HTTP server of BaseX), the server configuration is defined in 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/.

Maven

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 subdirectory. 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 jetty.xml and web.xml files as described above in the Servlet Container Configuration. The Jetty stop port can be changed in the Maven Jetty Plugin section in the pom.xml file.

Docker

The HTTP server can be run in a Docker container: our reference Dockerfile builds a lean image from an official release, exposes the HTTP server port, and keeps your databases on a mounted volume.

Services

The following services are available and enabled by default:

Name	Standard Path	Description
RESTXQ	`/`	Write enriched APIs and full web applications with XQuery.
WebSockets	`ws/`	Bidirectional client/server communication.
REST	`rest/`	Straightforward access to XML databases and their resources.
Default	`static/`	Access to static server resources (HTML, JavaScript, CSS, images, …).

The DBA is a web-based database administration interface written in RESTXQ. It allows you to create and administrate databases, evaluate queries in realtime, view log files, manage users, etc. It is embedded in the full distributions of BaseX, and it can be accessed after startup via http://localhost:8080/dba/.

Configuration

Unless BaseX is deployed as servlet, the location of the web application directory can be adjusted via the WEBPATH option, and compression of HTTP responses can be enabled via the GZIP option.

Further database options can be defined as context parameters in the web.xml file. The most important options for the web application context are:

Option	Default	Description
`USER`	empty	If a user is specified, no credentials must be passed on by the client. The option can also be assigned to a single servlet (see Authentication).
`HTTPLOCAL`	`true`	Operation mode. By default, all HTTP services are evaluated in the local database context. If the flag is set to `false`, a database server instance will be started in addition, as soon as the first HTTP service is called.
`RESTXQPATH`	`.`	Relative or absolute directory referencing the RESTXQ modules. By default, the option points to the standard web application directory.
`RESTPATH`	`.`	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.
`AUTHMETHOD`	`Basic`	The authentication method proposed by the server. The available methods are `Basic` and `Digest`.

All options are prefixed with org.basex.. Local file paths in options may be absolute or relative. If a relative path is specified, its root will be the servlet’s (webapp) path:

<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.

To enable or disable a specific service, the corresponding servlet entry in the web.xml file needs to be removed/commented.

Authentication

RESTXQ and WebSockets are run with admin permissions by default, as the supplied web.xml file assigns the admin user to the corresponding servlets. Web applications are supposed to authenticate their clients themselves; see Permissions for a full example.

Requests to the REST service are authenticated against the registered database users. If no default user is assigned, the credentials must be passed on by the client via Basic Authentication or Digest Authentication, depending on the chosen authentication method in the configuration. A default user can be specified with the USER option, e.g. as context parameter in the web.xml file:

<context-param>
  <param-name>org.basex.user</param-name>
  <param-value>rest-user</param-value>
</context-param>

The USER and AUTHMETHOD options can also be assigned to a single servlet. In the supplied web.xml file, the RESTXQ and WebSocket servlets are bound to the admin user:

<servlet>
  <servlet-name>RESTXQ</servlet-name>
  <servlet-class>org.basex.http.restxq.RestXqServlet</servlet-class>
  <init-param>
    <param-name>org.basex.user</param-name>
    <param-value>admin</param-value>
  </init-param>
</servlet>

If the init parameter is removed, the globally assigned user will be used. If no user is assigned at all, clients need to authenticate themselves before a request is processed.

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:

http://admin:...@localhost:8080/rest

Users are specified in a users.xml file, which is stored in the database directory (see User Management for more information).

Changelog

Version 13.0

Updated: BaseX is now based on the Jetty EE10 environment (Servlet 6.0).
Updated: No database server is started anymore by default (see HTTPLOCAL).

Version 12.0

Updated: BaseX is now based on Jetty 12.
Updated: An initial admin password is generated and written to the logs.

Version 11.0

Updated: BaseX is now based on version 11 of the Jetty Web Server.

Version 10.0

Updated: The default admin password has been removed, and the default ports have been changed from 8984/8985 to 8080/8081.

Version 9.0

Updated: jetty.xml configuration file (required for Jetty 9 and later).

Version 8.6

Updated: Authentication re-added to RESTXQ.
Updated: No password must be specified in the web.xml file anymore.
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

Added: jetty.xml: configuration for Jetty Server
Updated: server replaced with httplocal mode

Version 7.3

Updated: client mode replaced with server mode

Version 7.2

Updated: Web Application concept revised

⚡Generated with XQuery