https://github.com/Paradigm4/shim
Tip revision: d1a0c2b4462828682e9a3cff127a1e8a273ee6e1 authored by Bryan Lewis on 29 July 2013, 21:39:33 UTC
Added note about AFL support
Added note about AFL support
Tip revision: d1a0c2b
api.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>SciDB Simple HTTP Service</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link href="css/bootstrap.css" rel="stylesheet">
<style type="text/css">
body {
padding-top: 60px;
padding-bottom: 40px;
}
.allgreen
{
color: #007700;
}
.instances
{
-moz-column-count:3; /* Firefox */
-webkit-column-count:3; /* Safari and Chrome */
column-count:3;
-moz-column-gap:40px; /* Firefox */
-webkit-column-gap:40px; /* Safari and Chrome */
column-gap:40px;
}
table.api-param-values {
align: center;
width: 100%;
}
table.api-param-values th, table.api-param-values td {
text-align: left;
vertical-align: top;
padding: 6px 6px 6px 11px;
}
table.api-param-values tr {
width: 20px;
}
table.api-param-values tr:nth-child(2) td {
padding-top: 11px;
}
table.api-param-values tr:last-child td {
padding-bottom: 12px;
}
table.center-first-col tr td:first-child, table.center-first-col tr th:first-child {
text-align: center;
width: 70px;
}
table.api-param-values th {
background-color: #fafafa;
border-bottom: 1px solid #ddd;
}
</style>
<link href="css/bootstrap-responsive.css" rel="stylesheet">
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="../assets/js/html5shiv.js"></script>
<![endif]-->
<link rel="apple-touch-icon-precomposed" href="img/favicon.png">
<link rel="shortcut icon" href="img/favicon.ico">
</head>
<body>
<div class="navbar navbar-inverse navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="index.html">SciDB</a>
<div class="nav-collapse collapse">
<ul class="nav">
<li><a href="index.html">Dashboard</a></li>
<li><a href="query.html">Interactive Query</a></li>
<li><a href="help.html">Help</a></li>
<li class="active"><a href="api.html">HTTP API</a></li>
</ul>
<div class="pull-right">
<ul class="nav">
<li><a href="http://paradigm4.com">http://paradigm4.com</a>
<ul>
</div>
</div><!--/.nav-collapse -->
</div>
</div>
</div>
<div class="container">
<h2>Simple SciDB HTTP API</h2>
<p>
The SciDB HTTP Service implements a very simple API that clients may use
to interact with SciDB. The API consists of seven URIs (described in
detail below): /new_session, /release_session, /execute_query, /cancel,
/read_lines, /read_bytes, and /upload_file.
</p>
<p>
Clients always begin by requesting a <b>session ID</b> from the service, then
running a query and releasing the session ID when done. Note that session IDs
are distinct from SciDB query IDs--a session ID groups a SciDB query together
with server resources for input and output to the client.
</p>
<br/>
<h2>Example API Workflow</h2>
<ol>
<li> <b>/new_session</b>
<li> <b>/execute_query</b>
<li> <b>/read_lines</b> or <b>/read_bytes</b>
<li> <b>/release_session</b>
</ol>
<br/>
<h2>API Reference</h2>
We use the example URL http://scidb:8080 below. Parameters are required unless marked <i>optional</i>.
<br/><br/>
<div class="api">
<table class="api-param-values">
<tr>
<td colspan="2">
<h3>/new_session</h3>
<tr><td>DESCRIPTION
<td>Request a new HTTP session from the service.
<tr><td>METHOD<td>GET
<tr><td>PARAMETERS
<td>
<tr><td>RESPONSE
<td>Success: HTTP 200 and text session ID value in text/plain payload
<br/>
Failure (out of resources): HTTP 503
<tr><td>EXAMPLE
<td>
http://scidb:8080/new_session
<br/><br/>
<pre>
HTTP/1.0 200 OK
Content-Length: 3
Content-Type: text/plain
0
</pre>
<td>
<tr>
<td colspan="2">
<h3>/release_session</h3>
<tr><td>DESCRIPTION
<td>Release an HTTP session
<tr><td>METHOD<td>GET
<tr><td>PARAMETERS
<td><b>id</b> (an HTTP session ID)
<tr><td>RESPONSE
<td>Success: HTTP 200
<br/>
Failure (Session not found): HTTP 404
<br/>
Failure (invalid http query): HTTP 400
<tr><td>EXAMPLE
<td>
http://scidb:8080/release_session?id=0
<br/><br/>
<pre>
HTTP/1.0 200 OK
Content-Length: 0
Content-Type: text/plain
</pre>
<td>
<tr>
<td colspan="2">
<h3>/execute_query</h3>
<tr><td>DESCRIPTION
<td>Execute a SciDB query
<tr><td>METHOD<td>GET
<tr><td>PARAMETERS
<td>
<b>id</b> (an HTTP session ID)<br/>
<b>query</b> (query string, encoded for use in URL as required)<br/>
<b>save</b> <i>optional</i> (format string) Save the query output in the specified
format for subsequent by read_lines or read_bytes. If the save parameter is not
specified, don't save the query output. <br/>
<b>release</b> <i>optional</i> 0 or 1: if 1 then release_session as soon as query completes.
The default value is 0 if not specified.<br/>
<tr><td>RESPONSE
<td>
Success: HTTP 200 text/plain (SciDB Query ID)<br/>
Failure (SciDB connect error): HTTP 503 text/plain (SCIDB ERROR TEXT)
</br>
Failure (SciDB query error): HTTP 500 text/plain (SCIDB ERROR TEXT)
</br>
Failure (Invalid session): HTTP 404
<br/>
Failure (invalid http query): HTTP 400
</br>
<tr><td>NOTES
<td>500 and 503 errors result in removal of the web session ID and related resources (thus, release_session
does not have to be called after such an error). This
method blocks until the query completes. Do not specifiy the option relase=1 when the save option
is also set, or output will not be available to read_bytes or read_lines. Instead, explicitly call
release_session after reading is complete.
<tr><td>EXAMPLE
<td>
http://scidb:8080/execute_query?id=0&query=remove(x)&release=1
<br/><br/>
<pre>
HTTP/1.0 200 OK
Content-Length: 13
Content-Type: text/plain
1100993821834
</pre>
<td>
<tr><td>EXAMPLE (ERROR)
<td>
http://scidb:8080/execute_query?id=0&query=remove(x)&release=1
<br/><br/>
<pre>
HTTP/1.0 500 ERROR
Content-Length: 286
Content-Type: text/plain
UserQueryException in file: src/query/parser/ALTranslator.cpp function: createArrayReferenceParam line: 863
Error id: scidb::SCIDB_SE_QPROC::SCIDB_LE_ARRAY_DOESNT_EXIST
Error description: Query processor error. Array 'x' does not exist.
remove(x)
^
Failed query id: 1100994052246
</pre>
<tr>
<td>
<h3>/cancel</h3>
<tr><td>DESCRIPTION
<td>Cancel a SciDB query associated with a session
<tr><td>METHOD<td>GET
<tr><td>PARAMETERS
<td><b>id</b> (an HTTP session ID)
<tr><td>RESPONSE
<td>Success: HTTP 200
<br/>
Failure (session not found): HTTP 404
<br/>
Failure (invalid http query): HTTP 400
<br/>
Failure (could not connect to SciDB): HTTP 503
<tr><td>EXAMPLE
<td>
http://scidb:8080/cancel?id=0
<br/><br/>
<pre>
HTTP/1.0 200 OK
Content-Length: 0
Content-Type: text/plain
</pre>
<tr>
<td>
<h3>/read_lines</h3>
<tr><td>DESCRIPTION
<td>Read text lines from a query that saves its output
<tr><td>METHOD<td>GET
<tr><td>PARAMETERS
<td>
<b>id</b> (an HTTP session ID)<br/>
<b>n</b> (maximum number of lines to read and return) <br/>
<tr><td>RESPONSE
<td>Success: HTTP 200 followed by text/plain query result (up to <b>n</b> lines)
<br/>
Failure (invalid HTTP query string): HTTP 400 <br/>
Failure (session not found): HTTP 404 <br/>
Failure (end of file): HTTP 410 <br/>
Failure (invalid request): HTTP 414 <br/>
Failure (SciDB server error): HTTP 500<br/>
Failure (could not connect to SciDB server error): HTTP 503<br/>
Failure (server out of memory): HTTP 507<br/>
<tr><td>EXAMPLE
<td>
http://scidb:8080/new_session<br/>
http://scidb:8080/execute_query?id=0&query=list('functions')&save=dcsv<br/>
http://scidb:8080/read_lines?id=0&n=20
<br/><br/>
<pre>
HTTP/1.0 200 OK
Content-Length: 903
Content-Type: text/plain
{No} name,profile,deterministic,library
{0} "%","double %(double,double)",true,"scidb"
{1} "%","int16 %(int16,int16)",true,"scidb"
{2} "%","int32 %(int32,int32)",true,"scidb"
{3} "%","int64 %(int64,int64)",true,"scidb"
{4} "%","int8 %(int8,int8)",true,"scidb"
{5} "%","uint16 %(uint16,uint16)",true,"scidb"
{6} "%","uint32 %(uint32,uint32)",true,"scidb"
{7} "%","uint64 %(uint64,uint64)",true,"scidb"
{8} "%","uint8 %(uint8,uint8)",true,"scidb"
{9} "*","double *(double,double)",true,"scidb"
{10} "*","float *(float,float)",true,"scidb"
{11} "*","int16 *(int16,int16)",true,"scidb"
{12} "*","int32 *(int32,int32)",true,"scidb"
{13} "*","int64 *(int64,int64)",true,"scidb"
{14} "*","int8 *(int8,int8)",true,"scidb"
{15} "*","uint16 *(uint16,uint16)",true,"scidb"
{16} "*","uint32 *(uint32,uint32)",true,"scidb"
{17} "*","uint64 *(uint64,uint64)",true,"scidb"
{18} "*","uint8 *(uint8,uint8)",true,"scidb"
</pre>
<tr><td>NOTES
<td>
<ol>
<li>Set n=0 to download the entire output buffer.
<li>Be sure to properly url-encode special characters like the plus sign (+) in the request.
<li>When n>0, iterative requests to read_lines are allowed,
and will return at most the next n lines of output.
Use the 410 error code to detect end of file output.
</ol>
<tr>
<td>
<h3>/read_bytes</h3>
<tr><td>DESCRIPTION
<td>Read bytes from a query that saves its output
<tr><td>METHOD<td>GET
<tr><td>PARAMETERS
<td>
<b>id</b> (an HTTP session ID)<br/>
<b>n</b> (maximum number of bytes to read and return) <br/>
<tr><td>RESPONSE
<td>Success: HTTP 200 followed by application/octet-stream binary query result (up to <b>n</b> bytes)
<br/>
Failure (invalid HTTP query string): HTTP 400 <br/>
Failure (session not found): HTTP 404 <br/>
Failure (end of file): HTTP 410 <br/>
Failure (invalid request): HTTP 414 <br/>
Failure (SciDB server error): HTTP 500<br/>
Failure (could not connect to SciDB server error): HTTP 503<br/>
Failure (server out of memory): HTTP 507<br/>
<tr><td>EXAMPLE
<td>
http://scidb:8080/new_session<br/>
http://scidb:8080/execute_query?id=0&query=build(%3Cx:double%3E%5Bi=1:10,10,0%5D,random())&save=(double)<br/>
http://scidb:8080/read_bytes?id=0&n=20
<br/><br/>
<pre>
HTTP/1.0 200 OK
Content-Length: 20
Content-Type: application/octet-stream
Š/�A�}��A�
</pre>
<tr><td>NOTES
<td>
<ol>
<li>Iterative requests to read_lines are allowed, and will print at most the next n bytes of output.
Use the 410 error code to detect the end of output.
<li>Be sure to properly url-encode special characters in the request.
</ol>
<tr>
<td>
<h3>/upload_file</h3>
<tr><td>DESCRIPTION
<td>Upload a file to the HTTP service
<tr><td>METHOD<td>POST/GET
<tr><td>PARAMETERS
<td>
<b>id</b> (an HTTP session ID)<br/>
A valid file-upload HTTP POST message.
<tr><td>RESPONSE
<td>Success: HTTP 200 and the name of the file uploaded to the server in a text/plain response.
<br/>
Failure (invalid HTTP query string): HTTP 400 <br/>
Failure (Session not found): HTTP 404 <br/>
Failure (Server error): HTTP 500
<tr><td>EXAMPLE
<td>
<b>Example POST to session id=0:</b>
<br/>
<pre>
POST /upload_file?id=0 HTTP/1.1
Host: scidb:8080
Accept: */*
Content-Length: 526
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------d1f47951faa4
------------------------------d1f47951faa4
Content-Disposition: form-data; name="file"; filename="data.csv"
Content-Type: application/octet-stream
"","Sepal.Length","Sepal.Width","Petal.Length","Petal.Width","Species"
"1",5.1,3.5,1.4,0.2,"setosa"
"2",4.9,3,1.4,0.2,"setosa"
"3",4.7,3.2,1.3,0.2,"setosa"
"4",4.6,3.1,1.5,0.2,"setosa"
"5",5,3.6,1.4,0.2,"setosa"
"6",5.4,3.9,1.7,0.4,"setosa"
"7",4.6,3.4,1.4,0.3,"setosa"
"8",5,3.4,1.5,0.2,"setosa"
"9",4.4,2.9,1.4,0.2,"setosa"
------------------------------d1f47951faa4--
</pre>
<br/>
<b>Example response:</b>
<br/>
<pre>
HTTP/1.0 200 OK
Content-Length: 23
Content-Type: text/plain
/tmp/shim_file_Hrloh9
</pre>
<tr><td>NOTES
<td>
The file to upload can be binary. Use the returned server-side file name in a
subsequent SciDB load query, for example. The file does not persist after the
HTTP session is released.
</table>
</div>
</table>
<footer>
<br/><br/><p>© Paradigm4 2013</p>
</footer>
</div> <!-- /container -->
<script src="js/jquery.min.js"></script>
<script src="js/bootstrap.js"></script>
</body>
</html>
