Difference between revisions of "REST"
(19 intermediate revisions by 2 users not shown) | |||
Line 53: | Line 53: | ||
While '''Options''' can be specified for all operations, the remaining parameters will only make sense for '''Query''' and '''Run'''. | While '''Options''' can be specified for all operations, the remaining parameters will only make sense for '''Query''' and '''Run'''. | ||
− | =Request | + | =Request= |
− | ==GET | + | ==GET Method== |
If the GET method is used, all query parameters are directly specified within the URL. | If the GET method is used, all query parameters are directly specified within the URL. | ||
Line 62: | Line 62: | ||
* {{Code|query}}: Evaluate an XQuery expression. If a database or database path is specified in the URL, it is used as initial query context. | * {{Code|query}}: Evaluate an XQuery expression. If a database or database path is specified in the URL, it is used as initial query context. | ||
* {{Code|command}}: Execute a single [[Commands|database command]]. | * {{Code|command}}: Execute a single [[Commands|database command]]. | ||
− | * {{Code|run}}: Evaluate an XQuery file or command script located on the server. | + | * {{Code|run}}: Evaluate an XQuery file or command script located on the server. The file path is resolved against the directory specified by {{Option|RESTPATH}} (before, it was resolved against {{Option|WEBPATH}}). |
; Examples | ; Examples | ||
Line 74: | Line 74: | ||
* The next URL lists all database users that are known to BaseX:<br/><code>http://localhost:8984/rest?command=show+users</code> | * The next URL lists all database users that are known to BaseX:<br/><code>http://localhost:8984/rest?command=show+users</code> | ||
− | ==POST | + | ==POST Method== |
− | The body of a POST request is interpreted as XML fragment, which specifies the | + | The body of a POST request is interpreted as XML fragment, which specifies the operation to perform. |
− | operation to perform. The body | + | The name of the root element determines how the body will be evaluated: |
+ | |||
+ | * {{Code|commands}}: Run [[Commands#Command Scripts|Command Script]] | ||
+ | * {{Code|query}}: Execute XQuery expression | ||
+ | * {{Code|run}}: Run server-side file (query or command script) | ||
+ | * {{Code|command}}: Execute single command | ||
+ | |||
+ | The root element may be bound to the optional REST namespace. Existing command scripts can be sent to the server without any modifications: | ||
+ | |||
+ | * Create an empty database and return database information: | ||
+ | <pre class="brush:xml"> | ||
+ | <commands> | ||
+ | <create-db name='db'/> | ||
+ | <info-db/> | ||
+ | </commands> | ||
+ | </pre> | ||
+ | |||
+ | For the other commands, the following child elements are supported: | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! Name | ||
+ | ! Description | ||
+ | |- | ||
+ | | {{Code|text}} | ||
+ | | Required; contains the query string, command string, or file to be run | ||
+ | |- | ||
+ | | {{Code|parameter}} | ||
+ | | Serialization parameter (with {{Code|@name}} and {{Code|@value}} attributes) | ||
+ | |- | ||
+ | | {{Code|option}} | ||
+ | | Database option (with {{Code|@name}} and {{Code|@value}} attributes) | ||
+ | |- | ||
+ | | {{Code|variable}} | ||
+ | | Variable bindings | ||
+ | |- | ||
+ | | {{Code|context}} | ||
+ | | Initial context item | ||
+ | |} | ||
; Examples | ; Examples | ||
− | * | + | * Return the first five city names of the <b>factbook</b> database: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
− | <query xmlns="http://basex.org/rest"> | + | <rest:query xmlns:rest="http://basex.org/rest"> |
− | <text><![CDATA[ (//city/name)[position() <= 5] ]]></text> | + | <rest:text><![CDATA[ (//city/name)[position() <= 5] ]]></rest:text> |
− | </query> | + | </rest:query> |
</pre> | </pre> | ||
− | * | + | * Return string lengths of all text nodes that are found in the node that has been specified as initial context node: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
− | < | + | <query> |
− | < | + | <text>for $i in .//text() return string-length($i)</text> |
− | < | + | <context> |
<xml> | <xml> | ||
<text>Hello</text> | <text>Hello</text> | ||
<text>World</text> | <text>World</text> | ||
</xml> | </xml> | ||
− | </ | + | </context> |
− | </ | + | </query> |
</pre> | </pre> | ||
− | * | + | * Return the registered database users encoded in <code>ISO-8859-1</code>: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
− | <command | + | <command> |
<text>show users</text> | <text>show users</text> | ||
<parameter name='encoding' value='ISO-8859-1'/> | <parameter name='encoding' value='ISO-8859-1'/> | ||
Line 109: | Line 147: | ||
</pre> | </pre> | ||
− | * | + | * Create a new database from the specified input and preserve all whitespaces: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
− | <command | + | <command> |
<text>create db test http://files.basex.org/xml/xmark.xml</text> | <text>create db test http://files.basex.org/xml/xmark.xml</text> | ||
<option name='chop' value='false'/> | <option name='chop' value='false'/> | ||
Line 117: | Line 155: | ||
</pre> | </pre> | ||
− | * | + | * Bind value to the {{Code|$person}} variable and run query <code>find-person.xq</code>, which must be located in the directory specified by {{Option|WEBPATH}}: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
− | <run | + | <run> |
− | <text> | + | <variable name='person' value='Johannes Müller'/> |
+ | <text>find-person.xq</text> | ||
</run> | </run> | ||
</pre> | </pre> | ||
− | ==PUT | + | ==PUT Method== |
The PUT method is used to create new databases, or to add or update existing database resources: | The PUT method is used to create new databases, or to add or update existing database resources: | ||
Line 133: | Line 172: | ||
There are two ways to store non-XML data in BaseX: | There are two ways to store non-XML data in BaseX: | ||
− | * '''Store as | + | * '''Store as Raw Data''':<br/> If <code>application/octet-stream</code> is chosen as content-type, the input is added as [[Binary Data]]. |
* '''Convert to XML''':<br/> Incoming data is converted to XML if a parser is available for the specified content-type. The following content types are supported: | * '''Convert to XML''':<br/> Incoming data is converted to XML if a parser is available for the specified content-type. The following content types are supported: | ||
** <code>application/json</code>: Stores JSON as XML. | ** <code>application/json</code>: Stores JSON as XML. | ||
Line 140: | Line 179: | ||
** <code>text/html</code>: Stores HTML input as XML. | ** <code>text/html</code>: Stores HTML input as XML. | ||
− | + | Conversion can be influenced by specifying additional content-type parameters (see [[RESTXQ#Content Types|RESTXQ]] for more information). | |
If raw data is added and if no content type, or a wrong content, is specified, a <code>400</code> (BAD REQUEST) error will be raised. | If raw data is added and if no content type, or a wrong content, is specified, a <code>400</code> (BAD REQUEST) error will be raised. | ||
Line 158: | Line 197: | ||
Have a look at the [[REST#Usage Examples|usage examples]] for more detailed examples using Java and shell tools like cURL. | Have a look at the [[REST#Usage Examples|usage examples]] for more detailed examples using Java and shell tools like cURL. | ||
− | ==DELETE | + | ==DELETE Method== |
− | + | ||
The DELETE method is used to delete databases or resources within a database. | The DELETE method is used to delete databases or resources within a database. | ||
Line 171: | Line 210: | ||
=Assigning Variables= | =Assigning Variables= | ||
− | ==GET | + | ==GET Method== |
All query parameters that have not been processed before will be treated as variable assignments: | All query parameters that have not been processed before will be treated as variable assignments: | ||
Line 187: | Line 226: | ||
The dollar sign can be omitted as long as the variable name does not equal a parameter keyword (e.g.: <code>method</code>). | The dollar sign can be omitted as long as the variable name does not equal a parameter keyword (e.g.: <code>method</code>). | ||
− | ==POST | + | ==POST Method== |
If <code>query</code> or <code>run</code> is used as operation, external variables can be specified via the <code><variable/></code> element: | If <code>query</code> or <code>run</code> is used as operation, external variables can be specified via the <code><variable/></code> element: | ||
Line 203: | Line 242: | ||
</pre> | </pre> | ||
− | =Content Type= | + | =Response= |
+ | |||
+ | ==Content Type== | ||
As the content type of a REST response cannot necessarily be dynamically determined, it can be enforced by the user. The final content type of a REST response is chosen as follows: | As the content type of a REST response cannot necessarily be dynamically determined, it can be enforced by the user. The final content type of a REST response is chosen as follows: | ||
− | # If | + | # If the serialization parameter <code>[[Serialization|media-type]]</code> is supplied, it will be adopted as content-type. |
− | # Otherwise, if | + | # Otherwise, if the serialization parameter <code>[[Serialization|method]]</code> is supplied, the content-type will be chosen according to the following mapping: |
− | #* <code>xml</code> → <code>application/xml</code> | + | #* <code>xml</code>, <code>adaptive</code>, <code>basex</code> → <code>application/xml</code> |
#* <code>xhtml</code> → <code>text/html</code> | #* <code>xhtml</code> → <code>text/html</code> | ||
#* <code>html</code> → <code>text/html</code> | #* <code>html</code> → <code>text/html</code> | ||
#* <code>text</code> → <code>text/plain</code> | #* <code>text</code> → <code>text/plain</code> | ||
− | |||
#* <code>json</code> → <code>application/json</code> | #* <code>json</code> → <code>application/json</code> | ||
# If no media-type or serialization method is supplied, the content type of a response depends on the chosen REST operation: | # If no media-type or serialization method is supplied, the content type of a response depends on the chosen REST operation: | ||
Line 219: | Line 259: | ||
#* '''Command''' → <code>text/plain</code> | #* '''Command''' → <code>text/plain</code> | ||
#* '''Get''' → <code>application/xml</code>, or content type of the addressed resource | #* '''Get''' → <code>application/xml</code>, or content type of the addressed resource | ||
+ | |||
+ | Serialization parameters can either be supplied as [[#Parameters|query parameters]] or within the query. | ||
The following three example requests all return <code><a/></code> with <code>application/xml</code> as content-type: | The following three example requests all return <code><a/></code> with <code>application/xml</code> as content-type: | ||
Line 303: | Line 345: | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 9.0 | ||
+ | * Added: Support for command scripts in the [[#POST Method|POST Method]]. | ||
+ | * Updated: The REST namespace in the [[#POST Method|POST Method]] has become optional. | ||
;Version 8.1 | ;Version 8.1 | ||
− | * Added: | + | * Added: Support for input-specific content-type parameters |
− | * Updated: | + | * Updated: The [[#GET Method|run operation]] now resolves file paths against the {{Option|RESTPATH}} option. |
;Version 8.0 | ;Version 8.0 | ||
Line 312: | Line 358: | ||
;Version 7.9 | ;Version 7.9 | ||
− | * Updated: Also evaluate command scripts via the <code>[[#GET | + | * Updated: Also evaluate command scripts via the <code>[[#GET Method|run]]</code> operation. |
;Version 7.2 | ;Version 7.2 | ||
− | * Removed: | + | * Removed: Direct evaluation of adresses resources with <code>application/xquery</code> as content type |
;Version 7.1.1 | ;Version 7.1.1 | ||
Line 325: | Line 371: | ||
;Version 7.0 | ;Version 7.0 | ||
* REST API introduced, replacing the old JAX-RX API | * REST API introduced, replacing the old JAX-RX API | ||
− | |||
− | |||
− | |||
− |
Revision as of 15:30, 10 April 2019
This page presents one of the Web Application services. It describes how to use the REST API of BaseX.
BaseX offers a RESTful API for accessing database resources via URLs. 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.
Contents
Usage
By default, REST services are available at http://localhost:8984/rest/
. If no default credentials are specified in the URL or when starting the web application, they will be requested by the client (see further).
A web browser can be used to perform simple GET-based REST requests and display the response. Some alternatives for using REST are listed in the Usage Examples.
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://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:
<rest:database name="factbook" resources="1" xmlns:rest="http://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:
If a resource is not found, an HTTP response will be generated with 404
as status code.
Parameters
The following parameters can be applied to the operations:
- Variables:
External variables can be bound before a query is evaluated (see below for more). - Context:
Thecontext
parameter may be used to provide an initial XML context node. - Options:
Specified Options are applied before the actual operation will be performed. - 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.
While Options can be specified for all operations, the remaining parameters will only make sense for Query and Run.
Request
GET Method
If the GET method is used, all query parameters are directly specified within the URL. Additionally, the following operations can be specified:
query
: Evaluate an XQuery expression. If a database or database path is specified in the URL, it is used as initial query context.command
: Execute a single database command.run
: Evaluate an XQuery file or command script located on the server. The file path is resolved against the directory specified byRESTPATH
(before, it was resolved againstWEBPATH
).
- Examples
- Lists all resources found in the tmp path of the factbook database:
http://localhost:8984/rest/factbook/tmp
- Serializes a document as JSONML:
http://localhost:8984/rest/factbook/factbook.xml?method=json&json=format=jsonml
US-ASCII
is chosen as output encoding, and the queryeval.xq
is evaluated:http://localhost:8984/rest?run=eval.xq&encoding=US-ASCII
- The next URL lists all database users that are known to BaseX:
http://localhost:8984/rest?command=show+users
POST Method
The body of a POST request is interpreted as XML fragment, which specifies the operation to perform. The name of the root element determines how the body will be evaluated:
commands
: Run Command Scriptquery
: Execute XQuery expressionrun
: Run server-side file (query or command script)command
: Execute single command
The root element may be bound to the optional REST namespace. Existing command scripts can be sent to the server without any modifications:
- Create an empty database and return database information:
<commands> <create-db name='db'/> <info-db/> </commands>
For the other commands, the following child elements are supported:
Name | Description |
---|---|
text
|
Required; contains the query string, command string, or file to be run |
parameter
|
Serialization parameter (with @name and @value attributes)
|
option
|
Database option (with @name and @value attributes)
|
variable
|
Variable bindings |
context
|
Initial context item |
- Examples
- Return the first five city names of the factbook database:
<rest:query xmlns:rest="http://basex.org/rest"> <rest:text><![CDATA[ (//city/name)[position() <= 5] ]]></rest:text> </rest:query>
- Return string lengths of all text nodes that are found in the node that has been specified as initial context node:
<query> <text>for $i in .//text() return string-length($i)</text> <context> <xml> <text>Hello</text> <text>World</text> </xml> </context> </query>
- Return the registered database users encoded in
ISO-8859-1
:
<command> <text>show users</text> <parameter name='encoding' value='ISO-8859-1'/> </command>
- Create a new database from the specified input and preserve all whitespaces:
<command> <text>create db test http://files.basex.org/xml/xmark.xml</text> <option name='chop' value='false'/> </command>
- Bind value to the
$person
variable and run queryfind-person.xq
, which must be located in the directory specified byWEBPATH
:
<run> <variable name='person' value='Johannes Müller'/> <text>find-person.xq</text> </run>
PUT Method
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 input.
There are two ways to store non-XML data in BaseX:
- Store as Raw Data:
Ifapplication/octet-stream
is chosen as content-type, the input is added as Binary Data. - Convert to XML:
Incoming data is converted to XML if a parser is available for the specified content-type. The following content types are supported:application/json
: Stores JSON as XML.text/plain
: Stores plain text input as XML.text/comma-separated-values
: Stores CSV text input as XML.text/html
: Stores HTML input as XML.
Conversion can be influenced by specifying additional content-type parameters (see RESTXQ for more information).
If raw data is added and if no content type, or a wrong content, is specified, a 400
(BAD REQUEST) error will be raised.
- 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://localhost:8984/rest/XMark
- A new database is created, and no whitespaces will be removed from the passed on XML input:
http://localhost:8984/rest/XMark?chop=false
- 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://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).
Have a look at the usage examples for more detailed examples using Java and shell tools like cURL.
DELETE Method
The DELETE method is used to delete databases or resources within a database.
- Example
- The factbook database is deleted:
http://localhost:8984/rest/factbook
- All resources of the XMark database are deleted that reside in the tmp path:
http://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 Method
All query parameters that have not been processed before will be treated as variable assignments:
- Example
- The following request assigns two variables to a server-side query file
mult.xq
placed in the HTTP directory:http://localhost:8984/rest?run=mult.xq&$a=21&$b=2
(: XQuery file: mult.xq :) declare variable $a as xs:integer external; declare variable $b as xs:integer external; <mult>{ $a * $b }</mult>
The dollar sign can be omitted as long as the variable name does not equal a parameter keyword (e.g.: method
).
POST Method
If query
or run
is used as operation, external variables can be specified via the <variable/>
element:
<query xmlns="http://basex.org/rest"> <text><![CDATA[ declare variable $x as xs:integer external; declare variable $y as xs:integer external; <mult>{ $a * $b }</mult> ]]></text> <variable name="a" value="21"/> <variable name="b" value="2"/> </query>
Response
Content Type
As the content type of a REST response cannot necessarily be dynamically determined, it can be enforced by the user. The final content type of a REST response is chosen as follows:
- If the serialization parameter
media-type
is supplied, it will be adopted as content-type. - Otherwise, if the serialization parameter
method
is supplied, the content-type will be chosen according to the following mapping:xml
,adaptive
,basex
→application/xml
xhtml
→text/html
html
→text/html
text
→text/plain
json
→application/json
- If no media-type or serialization method is supplied, the content type of a response depends on the chosen REST operation:
- Query/Run →
application/xml
- Command →
text/plain
- Get →
application/xml
, or content type of the addressed resource
- Query/Run →
Serialization parameters can either be supplied as query parameters or within the query.
The following three example requests all return <a/>
with application/xml
as content-type:
http://localhost:8984/rest?query=%3Ca/%3E
http://localhost:8984/rest?query=%3Ca/%3E&method=xml
http://localhost:8984/rest?query=%3Ca/%3E&media-type=application/xml
Usage Examples
Java
Authentication
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:
import java.net.*; import org.basex.util.*; public final class RESTExample { public static void main(String[] args) throws Exception { // The java URL connection to the resource. URL url = new URL("http://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("HTTP response: " + conn.getResponseCode()); // Close connection. conn.disconnect(); } }
Content-Types
The content-type of the input can easily be included, just add the following property to the connection (in this example we explicitly store the input file as raw):
// store input as raw conn.setRequestProperty("Content-Type", "application/octet-stream");
See the PUT Requests section for a description of the possible content-types.
Find Java examples for all methods here: GET, POST, PUT, DELETE.
Command Line
Tools such as the Linux commands Wget or cURL exist to perform HTTP requests (try copy & paste):
- GET
curl -i "http://localhost:8984/rest/factbook?query=//city/name"
- POST
curl -i -X POST -H "Content-Type: application/xml" -d "<query xmlns='http://basex.org/rest'><text>//city/name</text></query>" "http://localhost:8984/rest/factbook"
curl -i -X POST -H "Content-Type: application/xml" -T query.xml "http://localhost:8984/rest/factbook"
- PUT
curl -i -X PUT -T "etc/xml/factbook.xml" "http://localhost:8984/rest/factbook"
curl -i -X PUT -H "Content-Type: application/json" -T "plain.json" "http://localhost:8984/rest/plain"
- DELETE
curl -i -X DELETE "http://admin:admin@localhost:8984/rest/factbook"
Changelog
- Version 9.0
- Added: Support for command scripts in the POST Method.
- Updated: The REST namespace in the POST Method has become optional.
- Version 8.1
- Added: Support for input-specific content-type parameters
- Updated: The run operation now resolves file paths against the
RESTPATH
option.
- Version 8.0
- Removed:
wrap
parameter
- Version 7.9
- Updated: Also evaluate command scripts via the
run
operation.
- Version 7.2
- Removed: Direct evaluation of adresses resources with
application/xquery
as content type
- Version 7.1.1
- Added:
options
parameter for specifying database options
- Version 7.1
- Added: PUT request: automatic conversion to XML if known content type is specified
- Version 7.0
- REST API introduced, replacing the old JAX-RX API