Server API

VXQuery could use a new method of executing queries and getting their result. One option would be to add a RESTful API. The API would allow  developers to use the system and allow for us to create a web-base interface for VXQuery. In addition the current CLI access method could be rewritten to use the same API. The new API would increase number of options a user or developer has when interacting with VXQuery. 

The big question is: What is the API? This page is here to define the API and an work surrounding it. A issue has been created in JIRA with sub-task to track all individual work items ( VXQUERY-180 - Getting issue details... STATUS ).

End Users of the API

• VXQuery's CLI
  • save-file VAL : File path to save the query result
  • Local only parameters
    • available-processors N : Number of available processors. (default java's available processors)
    • local-node-controllers N : Number of local node controllers (default 1)
  • Cluster only parameters
    • client-net-ip-address VAL : IP Address of the ClusterController
    • client-net-port N : Port of the ClusterController (default 1098)
• Application developers (new)
• Web-based query interface (new)

Possible Tools or Libraries

• http://swagger.io/ - Helpful to build, test and document an API
• https://github.com/ajaxorg/ace - Web-based editor with XQuery syntax highlighting
• https://atom.io/packages/language-jsoniq - Standalone editor with XQuery syntax highlighting
• http://developer.couchbase.com/documentation/server/4.0/n1ql/n1ql-rest-api/index.html - Couchbase API
• https://cwiki.apache.org/confluence/display/ASTERIXDB/New+HTTP+API+Design - AsterixDB API Proposal

Secondary Optionals

• http://bitworking.org/projects/atom/rfc5023.html - AtomPub
• http://www.odata.org/ - OData

API functions

/query (POST)

Sends a query to be executed with all the same parameters as the current CLI. The system sends back the job id and the result id.

See SwaggerIO Configuration for details on parameters and response values.

Example 1 (Basic request):

$ curl -v http://localhost:????/query -X POST \
-d "statement=for $x in doc('books.xml')/bookstore/book/title return $x" 

< HTTP/1.1 200 OK
<response>
  <requestId>6e0143ed-4657-4c9d-a184-703c930c7401</requestId>
  <status>success</status>
  <resultId>1</resultId>
  <resultUrl>http://localhost:????/query/result/1</resultUrl>
</response>

Example 2 (Basic request with additional parameters):

$ curl -v http://localhost:????/query -X POST \
-d "statement=for $x in doc('books.xml')/bookstore/book/title return $x&frameSize=128000&showOptimizedExpressionTree=true&metrics=true" 

< HTTP/1.1 200 OK
<response>
  <requestId>6e0143ed-4657-4c9d-a184-703c930c7401</requestId>
  <status>fatal</status>
  <resultId>2</resultId>
  <resultUrl>http://localhost:????/query/result/2</resultUrl>
  <metrics>
     <elapsedTime>134</elapsedTime>
     <compileTime>110</compileTime>
  </metrics>
  <optimizedExpressionTree>
DISTRIBUTE-RESULT( $$17 )
UNNEST( $$17:child($$13, "title") )
UNNEST( $$13:child($$7, "book") )
UNNEST( $$7:child($$2, "bookstore") )
ASSIGN( $$2:doc("books.xml") )
EMPTY-TUPLE-SOURCE
  </optimizedExpressionTree>
</response>

Example 3 (Bad request):

$ curl -v http://localhost:????/query -X POST \
-d "statement=for $x in doc('ooks.xml')/bookstore/book/title return $x" 

< HTTP/1.1 400 Bad Request
<response>
  <requestID>6e0143ed-4657-4c9d-a184-703c930c7401</requestID>
  <status>fatal</status>
  <error>
    <code>400</code>
    <message>Bad Request</message>
    <stackTrace>...</stackTrace>
  </error>
  <queryError>
    <code>FODC0002</code>
    <message>Error retrieving resource.</message>
  </queryError>

</response>

The VXQuery SystemException should be parsed into the queryError tag separating out the code and message. The stackTrace tag may include the java stack trace of the error message.

/query/result/{result-id} (GET)

Requests the query result for the result id. The system may response saying the job is not done, thus the result is not ready.

See SwaggerIO Configuration for details on parameters and response values.

Example 1 (Basic request):

$ curl -v http://localhost:????/query/result/1 -X POST

< HTTP/1.1 200 OK
<response>
  <requestId>6e0143ed-4657-4c9d-a184-703c930c7401</requestId>
  <status>success</status>
  <result>
    <title lang="en">Everyday Italian</title>
    <title lang="en">Harry Potter</title>
    <title lang="en">XQuery Kick Start</title>
    <title lang="en">Learning XML</title>
  </result>
</response>

Example 2 (Basic request with additional parameters):

$ curl -v http://localhost:????/query/result/2 -X POST \
-d "metrics=true" 

< HTTP/1.1 200 OK
<response>
  <requestId>6e0143ed-4657-4c9d-a184-703c930c7401</requestId>
  <status>success</status>
  <result>
    <title lang="en">Everyday Italian</title>
    <title lang="en">Harry Potter</title>
    <title lang="en">XQuery Kick Start</title>
    <title lang="en">Learning XML</title>
  </result>
  <metrics>
     <elapsedTime>123</elapsedTime>
  </metrics>
</response>

AsterixDB Code References

• org.apache.asterix.api.http.servlet.APIServlet.java
• org.apache.asterix.api.http.servlet.RESTAPIServlet.java
• org.apache.asterix.hyracks.bootstrap.CCApplicationEntryPoint.java
• https://atom.io/packages/language-jsoniq