REST

From BaseX Documentation
Revision as of 15:23, 26 September 2011 by Michael (talk | contribs) (→‎User Management: changed user.... to org....)
Jump to navigation Jump to search

This page is part of the Developer Section. It describes how to use the REST API of BaseX.

BaseX offers a RESTful API for accessing distributed XML resources. REST (REpresentational State Transfer) facilitates a simple and fast access to databases through HTTP. The HTTP methods GET, PUT, DELETE, and POST can be used to interact with the database.

The REST implementation has formerly been based on JAX-RX, a generic layer to provide unified access to XML databases and resources. With Version 6.8, it has been replaced with a native REST implementation that allows a closer integration with XQuery, WebDAV, and other features of BaseX. If you have worked with JAX-RX before, please take some time to understand the differences between the old and new API.

Starting HTTP Server

First of all, launch the BaseX HTTP Server, which will itself start an instance of the Jetty WebServer that listens to the default port 8984 (check out the additional command-line options).

Most browsers can be used to get to know the REST API, and to directly display the results. Some more alternatives for using REST are listed in the Usage Examples below.

URL Architecture

The root URL lists all available databases. The following examples assume that you have created a database instance from the factbook.xml document:

http://admin:admin@localhost:8984/rest
 
<rest:databases resources="1" xmlns:rest="http://www.basex.org/rest">
  <rest:database resources="1" size="1813599">factbook</rest:database>
</rest:databases>

The resources of a database can be listed by specifying the database, and potential sub directories, in the URL. In the given example, a single XML document is stored in the factbook database:

http://admin:admin@localhost:8984/rest/factbook
 
<rest:database name="factbook" resources="1" xmlns:rest="http://www.basex.org/rest">
  <rest:resource type="xml" content-type="application/xml" size="77192">factbook.xml</rest:resource>
</rest:database>

The contents of a database can be retrieved by directly addressing the resource:

http://admin:admin@localhost:8984/rest/factbook/factbook.xml

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

Operations

GET and POST requests support the following operations:

  • Query:
    Evaluates an XPath/XQuery expression. If a database or database path is specified in the URL, it is used as initial query context.
  • Run:
    Runs a query file located on the server. The query directory is defined by the HTTPPATH option.
  • Command:
    Executes a database command.
  • Get:
    This is the default operation if the GET request is used and no other operation is specified. 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.

Parameters

The following parameters can be applied to the query and run operations:

  • Variables:
    External variables can be bound before a query is evaluated (see below for more).
  • Context:
    The context parameter may be used to provide an initial XML context node.
  • Serialization:
    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.
  • Wrap:
    The wrap parameter encloses all query results with XML elements, using the http://www.basex.org/rest namespace.

Request Methods

GET Requests

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

Examples

POST Requests

The body of a POST request is interpreted as XML fragment, which specifies the operation to perform. The body must conform to a given REST POST Schema.

Examples
  • The following query returns the first five city names of the factbook database:
<query xmlns="http://www.basex.org/rest">
  <text><![CDATA[ (//city/name)[position() <= 5] ]]></text>
</query>
  • 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:
<rest:query xmlns:rest="http://www.basex.org/rest">
  <rest:text>for $i in .//text() return string-length($i)</rest:text>
  <rest:context>
    <xml>
      <text>Hello</text>
      <text>World</text>
    </xml>
  </rest:context>
</rest:query>
  • The following request returns the registered database users encoded in ISO-8859-1:
<command xmlns="http://www.basex.org/rest">
  <text>show users</text>
  <parameter name='encoding' value='ISO-8859-1'/>
</command>

PUT Requests

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

  • Create Database:
    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.
  • Store Resource:
    A resource is added to the database if the URL contains a database path. If the addressed resource already exists, it is replaced by the new XML input.

If a content type different to application/xml is specified in the request header, the data will be stored as raw resource.

Examples
  • A new database with the name XMark is created. If XML input is sent in the HTTP body, the resulting database resource will be called XMark.xml:
    http://admin:admin@localhost:8984/rest/XMark
  • The contents of the HTTP body will be taken as input for the document one.xml, which will be stored in the XMark database:
    http://admin:admin@localhost:8984/rest/XMark/one.xml

An HTTP response with status code 201 (CREATED) is sent back if the operation was successful. Otherwise, the server will reply with 404 (if a specified database was not found) or 400 (if the operation could not be completed).

DELETE Requests

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

Example
  • The factbook database is deleted:
    http://admin:admin@localhost:8984/rest/factbook
  • All resources of the XMark database are deleted that reside in the tmp path:
    http://admin:admin@localhost:8984/rest/XMark/tmp/

The HTTP status code 404 is returned if no database is specified. 200 (OK) will be sent in all other cases.

Assigning Variables

GET Requests

Query parameters prefixed with a dollar sign ($) will be handled as external variables:

Query:

declare variable $x as xs:integer external;
$x

Parameters:

Assign the variable with: &$x=21

Complete request (compact notation, omitting the optional variable declaration):

http://admin:admin@localhost:8984/rest?query=$x&$x=21

POST Requests

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

<query xmlns="http://www.basex.org/rest">
  <text>
    declare variable $x as xs:integer external;
    declare variable $y as xs:integer external;
    $x * $y
  </text>
  <variable name="x" value="21"/>
  <variable name="y" value="2"/>
</query>

User Management

By default, the HTTP server is started with no predefined user. Users and passwords can be sent via HTTP basic authentication with each HTTP request. As alternative, users and passwords can also be stored in the "org.basex.user" and "org.basex.password" system properties before the HTTP server is started, or specified as command-line arguments.

With most browsers and with cURL, you can specify the user name and password with each HTTP request within the request string as plain text, using the format USER:PASSWORD@URL. An example:

http://admin:admin@localhost:8984/rest/factbook

Content Type

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:

  1. By default, the content type of a response depends on the chosen operation:
    • Query/Runapplication/xml
    • Commandtext/plain
    • Getapplication/xml, or content type of the addressed resource
  2. The default content type is overwritten if a serialization method is specified, either as query parameter or within the XQuery expression. The following methods are available:
    • xmlapplication/xml
    • xhtmltext/html
    • htmltext/html
    • texttext/plain
    • rawapplication/octet-stream
    • json or jsonmlapplication/json
  3. The content type is overwritten in any case if a specific media-type is chosen, again as query parameter or within the query.

The following three example requests will all return <a/> as result and use application/xml as content-type:

http://admin:admin@localhost:8984/rest?query=%3Ca/%3E
http://admin:admin@localhost:8984/rest?query=%3Ca/%3E&method=xml
http://admin:admin@localhost:8984/rest?query=%3Ca/%3E&media-type=application/xml

Usage Examples

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.

Basic access authentication can be activated in Java by adding an authorization header to the HttpURLConnection instance. The header contains the word Basic, which specifies the authentication method, followed by the Base64-encoded USER:PASSWORD pair. As Java does not include a default conversion library for Base64 data, the internal BaseX class org.basex.util.Base64 can be used for that purpose:

// The java URL connection to the resource. 
URL url = new URL("http://admin:admin@localhost:8984/rest/factbook"); 
 
// Establish the connection to the URL. 
HttpURLConnection conn = (HttpURLConnection) url.openConnection(); 
// Set as DELETE request. 
conn.setRequestMethod("DELETE"); 

// User and password.
String user = "bob";
String pw ="alice";
// Encode user name and password pair with a base64 implementation.
String encoded = Base64.encode(user + ":" + pw);
// Basic access authentication header to connection request.
conn.setRequestProperty("Authorization", "Basic " + encoded);
 
// Print the HTTP response code. 
System.out.println("\n* HTTP response: " + conn.getResponseCode()); 
 
// Close connection. 
conn.disconnect(); 

Find Java examples for all methods here: GET, POST (Add), POST (Query), PUT, DELETE.

Command Line

Tools such as the Linux commands Wget or cURL exist to perform HTTP requests (try copy & paste):

GET
curl -i "admin:admin@localhost:8984/rest/factbook?query=//city/name&count=5"
POST
curl -i -X POST -H "Content-Type: application/xml" -d
"<query xmlns='http://www.basex.org/rest'><text>//city/name</text><parameter name='count' value='5'/></query>"
"admin:admin@localhost:8984/rest/factbook"
curl -i -X POST -H "Content-Type: application/xml" -T query.xml "admin:admin@localhost:8984/rest/factbook"
PUT
curl -i -X PUT -T "etc/xml/factbook.xml" "admin:admin@localhost:8984/rest/factbook"
DELETE
curl -i -X DELETE "admin:admin@localhost:8984/rest/factbook"