Difference between revisions of "REST"
Line 7: | Line 7: | ||
interact with the database. | interact with the database. | ||
− | The REST implementation has formerly been | + | The REST implementation has formerly been based on [http://jax-rx.sourceforge.net JAX-RX], |
− | based on [http://jax-rx.sourceforge.net JAX-RX], | + | a generic layer to provide unified access to XML databases and resources. With |
− | provide unified access to XML databases and resources. With | + | <font color='orangered'>Version 6.8</font>, it has been replaced with a native REST |
− | <font color='orangered'>Version 6.8</font>, it has been replaced with a native | + | 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 | |
− | XQuery, WebDAV, and other features of BaseX. | + | understand the differences between the old and new API. |
==Starting HTTP Server== | ==Starting HTTP Server== | ||
− | |||
− | 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]] | + | 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]] below. | ||
==URL Architecture== | ==URL Architecture== | ||
Line 43: | Line 45: | ||
</pre> | </pre> | ||
− | The contents of a database can be | + | The contents of a database can be retrieved by adding 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> | :<code>[http://admin:admin@localhost:8984/rest/factbook?query http://admin:admin@localhost:8984/rest/factbook?query]</code> | ||
Line 49: | Line 51: | ||
If a resource is not found, an HTTP response will be generated with <code>404</code> as status code. | If a resource is not found, an HTTP response will be generated with <code>404</code> as status code. | ||
− | === | + | ===Operations=== |
− | GET and POST requests | + | GET and POST requests support the following three '''operations''': |
− | |||
− | * <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 query context. | + | * <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>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]]. | * <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: | The following parameters can be applied to the <code>query</code> and <code>run</code> operations: | ||
− | * ''' | + | |
− | + | * '''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>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>). | * <code>wrap</code>:<br/>Wraps the results in XML elements (default: <code>no</code>). | ||
Line 68: | Line 72: | ||
===GET Requests=== | ===GET Requests=== | ||
− | + | If the GET method is used, all query parameters are directly specified within the URL. | |
The following example prints the city names from the ''factbook'' database: | 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/factbook?query=//city/name http://admin:admin@localhost:8984/rest/factbook?query=//city/name]</code> | ||
− | + | In the next request, <code>US-ASCII</code> is chosen as output encoding, and the database is opened within the XQuery expression: | |
:<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> | :<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 | + | The next URL turns on XML wrapping and lists all database users 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> | :<code>[http://admin:admin@localhost:8984/rest?command=show+users http://admin:admin@localhost:8984/rest?command=show+users]</code> | ||
===POST Requests=== | ===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 | + | The following query returns the first five city names of the <b>factbook</b> database: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
<query xmlns="http://www.basex.org/rest"> | <query xmlns="http://www.basex.org/rest"> | ||
Line 105: | Line 99: | ||
</pre> | </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: | + | 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"> | <pre class="brush:xml"> | ||
<rest:query xmlns:rest="http://www.basex.org/rest"> | <rest:query xmlns:rest="http://www.basex.org/rest"> | ||
Line 118: | Line 113: | ||
</pre> | </pre> | ||
− | The following | + | The following request returns the registered database users encoded in <code>ISO-8859-1</code>: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
<command xmlns="http://www.basex.org/rest"> | <command xmlns="http://www.basex.org/rest"> | ||
Line 128: | Line 123: | ||
===PUT Requests=== | ===PUT Requests=== | ||
− | The PUT method | + | The PUT method 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 path''. If the addressed document already exists, it is replaced by the new XML input. | ||
− | ; | + | ; Examples |
− | |||
− | + | * <code>localhost:8984/rest/XMark</code>:<br/>A new database with the name <b>XMark</b> is created. If XML input is sent in the HTTP body, the resulting databasse document will be called <b>XMark.xml</b>. | |
− | : A new database with the name <b>XMark</b> is created | + | * <code>localhost:8984/rest/XMark/one.xml</code>: The contents of the HTTP body will be taken as input for the document <b>one.xml</b>, which will be stored in the <b>XMark</b> database. |
− | + | An HTTP response with status code <code>201</code> (CREATED) | |
− | Otherwise, <code>404</code> | + | is sent back if the operation was successful. Otherwise, |
+ | the server will reply with <code>404</code> (if a specified | ||
+ | database was not found) or <code>400</code> (if the operation | ||
+ | could not be completed). | ||
===DELETE Requests=== | ===DELETE Requests=== | ||
− | The DELETE method | + | The DELETE method is used to delete databases or resources within a database. |
− | ; | + | ; Example |
− | : | + | * <code>localhost:8984/rest/factbook</code>:<br/>The <b>factbook</b> database is deleted |
− | + | * <code>localhost:8984/rest/XMark/tmp/</code>:<br/>All resources of the <b>XMark</b> database are deleted that reside in the <b>tmp</b> path. | |
− | + | ||
− | + | The HTTP status code <code>404</code> is returned if no database is specified. | |
− | + | <code>200</code> (OK) will be sent in all other cases. | |
− | |||
− | |||
==Assigning Variables== | ==Assigning Variables== | ||
===GET Requests=== | ===GET Requests=== | ||
+ | |||
Query parameters prefixed with a dollar sign (<code>$</code>) will be handled as external variables: | Query parameters prefixed with a dollar sign (<code>$</code>) will be handled as external variables: | ||
Line 163: | Line 162: | ||
</pre> | </pre> | ||
− | + | Parameters: | |
:Assign the variable with: <code>&$x=21</code> | :Assign the variable with: <code>&$x=21</code> | ||
− | Complete request (compact notation, omitting the | + | Complete request (compact notation, omitting the optional variable declaration): |
− | :http://admin:admin@localhost:8984/rest?query=$x&$x=21 | + | :<code>http://admin:admin@localhost:8984/rest?query=$x&$x=21</code> |
===POST Requests=== | ===POST Requests=== | ||
− | Using POST, the <code><variable/></code> element is used to | + | Using POST, the <code><variable/></code> element is used to specify external variables: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
Line 187: | Line 186: | ||
==User Management== | ==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 | + | 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 authentication] | ||
+ | with each HTTP request. As alternative, users and passwords can also be 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 | + | 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 <code>USER:PASSWORD@URL</code>. An example: | ||
− | + | : <code>http://admin:admin@localhost:8984/rest/factbook</code> | |
− | :<code> | ||
==Content Type== | ==Content Type== | ||
− | As the | + | 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: |
# By default, the content type of a response depends on the chosen operation: | # By default, the content type of a response depends on the chosen operation: | ||
Line 217: | Line 221: | ||
===Java=== | ===Java=== | ||
+ | |||
Most programming languages offer libraries to communicate with HTTP servers. | 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. | The following example demonstrates how easy it is to perform a DELETE request with Java. | ||
Line 255: | Line 260: | ||
===Command Line=== | ===Command Line=== | ||
− | + | ||
− | [http://curl.haxx.se/ cURL] exist to | + | Tools such as the Linux commands [http://www.gnu.org/s/wget/ Wget] or [http://curl.haxx.se/ cURL] exist to |
perform HTTP requests (try copy & paste): | perform HTTP requests (try copy & paste): | ||
Revision as of 17:57, 24 September 2011
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 applied 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.
Contents
Starting HTTP Server
First of all, please launch a HTTP Server instance of BaseX: run the basexhttp
script, or double click on the BaseX Server (Start) start icon in Windows. Follow this link for some more information (or check out the additional 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 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:
<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 document is stored in the factbook database:
<rest:database name="factbook" resources="1" xmlns:rest="http://www.basex.org/rest"> <rest:resource type="xml" size="77192">factbook.xml</rest:resource> </rest:database>
The contents of a database can be retrieved by adding an empty query parameter to the path:
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 three 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 theHTTPPATH
option.command
:
Executes a database command.
Parameters
The following parameters can be applied to the query
and run
operations:
- 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. - Variables:
External variables can be bound before a query is evaluated (see below for more). context
:
May be used to provide an initial context node.wrap
:
Wraps the results in XML elements (default:no
).
Request Methods
GET Requests
If the GET method is used, all query parameters are directly specified within the URL. The following example prints the city names from the factbook database:
In the next request, US-ASCII
is chosen as output encoding, and the database is opened within the XQuery expression:
The next URL turns on XML wrapping and lists all database users that are known to BaseX:
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:
- 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 path. If the addressed document already exists, it is replaced by the new XML input.
- Examples
localhost:8984/rest/XMark
:
A new database with the name XMark is created. If XML input is sent in the HTTP body, the resulting databasse document will be called XMark.xml.localhost:8984/rest/XMark/one.xml
: The contents of the HTTP body will be taken as input for the document one.xml, which will be stored in the XMark database.
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
localhost:8984/rest/factbook
:
The factbook database is deletedlocalhost:8984/rest/XMark/tmp/
:
All resources of the XMark database are deleted that reside in the tmp path.
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):
POST Requests
Using POST, the <variable/>
element is used to specify external variables:
<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 "user.basex.user" and "user.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:
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:
- By default, the content type of a response depends on the chosen operation:
- Command results are returned as
text/plain
- Query results are returned as
application/xml
- Command results are returned as
- 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:
xml
→application/xml
xhtml
→text/html
html
→text/html
text
→text/plain
raw
→application/octet-stream
json
orjsonml
→application/json
- 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 (Add)
curl -i -H "Content-Type: text/xml" -d "<HelloWorld/>" "admin:admin@localhost:8984/rest/world/hello.xml"
- POST (Query)
curl -i -X POST -H "Content-Type: application/query+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/query+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"