Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

issue #648: /batch API is missing from Web Interface API Docummentation (Swagger)

This commit is contained in:
Jan Steemann 2013-10-29 04:43:34 +01:00
parent 0131735f30
commit 2e301f118d
5 changed files with 132 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG
View File

@ -1,6 +1,8 @@
v1.4.0 (2013-10-28)
-------------------
* fixed issue #648: /batch API is missing from Web Interface API Docummentation (Swagger)
* fixed issue #647: Icon tooltips missing
* fixed issue #646: index creation in web interface

1
Documentation/Scripts/generateSwaggerApi.py
View File

@ -43,6 +43,7 @@ import sys, os, json, string
files = {
"js/actions/api-aqlfunction.js" : "aqlfunction",
"arangod/RestHandler/RestBatchHandler.cpp" : "batch",
"js/actions/api-collection.js" : "collection",
"js/actions/api-cursor.js" : "cursor",
"js/actions/api-database.js" : "database",

88
arangod/RestHandler/RestBatchHandler.cpp
View File

@ -76,7 +76,83 @@ RestBatchHandler::~RestBatchHandler () {
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// {@inheritDoc}
/// @brief executes a batch request
///
/// @RESTHEADER{POST /_api/batch,executes a batch request}
///
/// @RESTBODYPARAM{body,string,required}
/// The multipart batch request, consisting of the envelope and the individual
/// batch parts.
///
/// @RESTDESCRIPTION
/// Executes a batch request. A batch request can contain any number of
/// other requests that can be sent to ArangoDB in isolation. The benefit of
/// using batch requests is that batching requests requires less client/server
/// roundtrips than when sending isolated requests.
///
/// All parts of a batch request are executed serially on the server. The
/// server will return the results of all parts in a single response when all
/// parts are finished.
///
/// Technically, a batch request is a multipart HTTP request, with
/// content-type `multipart/form-data`. A batch request consists of an
/// envelope and the individual batch part actions. Batch part actions
/// are "regular" HTTP requests, including full header and an optional body.
/// Multiple batch parts are separated by a boundary identifier. The
/// boundary identifier is declared in the batch envelope. The MIME content-type
/// for each individual batch part must be `application/x-arango-batchpart`.
///
/// The response sent by the server will be an `HTTP 200` response, with an
/// error summary header `x-arango-errors`. This header contains the number of
/// batch parts that failed with an HTTP error code of at least 400.
///
/// The response sent by the server is a multipart response, too. It contains
/// the individual HTTP responses for all batch parts, including the full HTTP
/// result header (with status code and other potential headers) and an
/// optional result body. The individual batch parts in the result are
/// seperated using the same boundary value as specified in the request.
///
/// The order of batch parts in the response will be the same as in the
/// original client request. Client can additionally use the `Content-Id`
/// MIME header in a batch part to define an individual id for each batch part.
/// The server will return this id is the batch part responses, too.
///
/// @RESTRETURNCODES
///
/// @RESTRETURNCODE{200}
/// is returned if the batch was received successfully. HTTP 200 is returned
/// even if one or multiple batch part actions failed.
///
/// @RESTRETURNCODE{400}
/// is returned if the batch envelope is malformed or incorrectly formatted.
/// This code will also be returned if the content-type of the overall batch
/// request or the individual MIME parts is not as expected.
///
/// @RESTRETURNCODE{405}
/// is returned when an invalid HTTP method is used.
///
/// @EXAMPLES
///
/// @EXAMPLE_ARANGOSH_RUN{RestBatch1}
/// var parts = [
/// "Content-Type: application/x-arango-batchpart\r\nContent-Id: myId1\r\n\r\nGET /_api/version HTTP/1.1\r\n",
/// "Content-Type: application/x-arango-batchpart\r\nContent-Id: myId2\r\n\r\nDELETE /_api/collection/products HTTP/1.1\r\n",
/// "Content-Type: application/x-arango-batchpart\r\nContent-Id: someId\r\n\r\nPOST /_api/collection/products HTTP/1.1\r\n\r\n{ \"name\": \"products\" }\r\n",
/// "Content-Type: application/x-arango-batchpart\r\nContent-Id: nextId\r\n\r\nGET /_api/collection/products/figures HTTP/1.1\r\n",
/// "Content-Type: application/x-arango-batchpart\r\nContent-Id: otherId\r\n\r\nDELETE /_api/collection/products HTTP/1.1\r\n"
/// ];
/// var boundary = "SomeBoundaryValue";
/// var headers = { "Content-Type" : "multipart/form-data; boundary=" + boundary };
/// var body = "--" + boundary + "\r\n" +
/// parts.join("\r\n" + "--" + boundary + "\r\n") +
/// "--" + boundary + "--\r\n";
///
/// var response = logCurlRequestRaw('POST', '/_api/batch', body, headers);
///
/// assert(response.code === 200);
///
/// logRawResponse(response);
/// @END_EXAMPLE_ARANGOSH_RUN
////////////////////////////////////////////////////////////////////////////////
Handler::status_e RestBatchHandler::execute() {
@ -130,13 +206,14 @@ Handler::status_e RestBatchHandler::execute() {
const size_t partLength = helper.foundLength;
const char* headerStart = partStart;
char* bodyStart = NULL;
char* bodyStart = 0;
size_t headerLength = 0;
size_t bodyLength = 0;
// assume Windows linebreak \r\n\r\n as delimiter
char* p = strstr((char*) headerStart, "\r\n\r\n");
if (p != NULL) {
if (p != 0 && p + 4 <= partEnd) {
headerLength = p - partStart;
bodyStart = p + 4;
bodyLength = partEnd - bodyStart;
@ -144,7 +221,8 @@ Handler::status_e RestBatchHandler::execute() {
else {
// test Unix linebreak
p = strstr((char*) headerStart, "\n\n");
if (p != NULL) {
if (p != 0 && p + 2 <= partEnd) {
headerLength = p - partStart;
bodyStart = p + 2;
bodyLength = partEnd - bodyStart;
@ -180,7 +258,6 @@ Handler::status_e RestBatchHandler::execute() {
request->setHeader("authorization", 13, authorization.c_str());
}
HttpHandler* handler = _server->createHandler(request);
if (! handler) {
@ -221,6 +298,7 @@ Handler::status_e RestBatchHandler::execute() {
}
HttpResponse* partResponse = handler->getResponse();
if (partResponse == 0) {
delete handler;
generateError(HttpResponse::BAD, TRI_ERROR_INTERNAL, "could not create a response for batch part request");

4
js/apps/system/aardvark/api-docs.json
View File

@ -6,6 +6,10 @@
"path": "api-docs/aqlfunction.{format}",
"description": "aqlfunction API"
},
{
"path": "api-docs/batch.{format}",
"description": "batch API"
},
{
"path": "api-docs/collection.{format}",
"description": "collection API"

42
js/apps/system/aardvark/api-docs/batch.json Normal file
View File

@ -0,0 +1,42 @@
{
"basePath": "/",
"swaggerVersion": "1.1",
"apiVersion": "0.1",
"apis": [
{
"operations": [
{
"errorResponses": [
{
"reason": "is returned if the batch was received successfully. HTTP 200 is returned even if one or multiple batch part actions failed. ",
"code": "200"
},
{
"reason": "is returned if the batch envelope is malformed or incorrectly formatted. This code will also be returned if the content-type of the overall batch request or the individual MIME parts is not as expected. ",
"code": "400"
},
{
"reason": "is returned when an invalid HTTP method is used. ",
"code": "405"
}
],
"parameters": [
{
"dataType": "String",
"paramType": "body",
"required": "true",
"name": "body",
"description": "The multipart batch request, consisting of the envelope and the individual batch parts. "
}
],
"notes": "Executes a batch request. A batch request can contain any number of other requests that can be sent to ArangoDB in isolation. The benefit of using batch requests is that batching requests requires less client/server roundtrips than when sending isolated requests. <br><br>All parts of a batch request are executed serially on the server. The server will return the results of all parts in a single response when all parts are finished. <br><br>Technically, a batch request is a multipart HTTP request, with content-type <em>multipart/form-data</em>. A batch request consists of an envelope and the individual batch part actions. Batch part actions are \"regular\" HTTP requests, including full header and an optional body. Multiple batch parts are separated by a boundary identifier. The boundary identifier is declared in the batch envelope. The MIME content-type for each individual batch part must be <em>application/x-arango-batchpart</em>. <br><br>The response sent by the server will be an <em>HTTP 200</em> response, with an error summary header <em>x-arango-errors</em>. This header contains the number of batch parts that failed with an HTTP error code of at least 400. <br><br>The response sent by the server is a multipart response, too. It contains the individual HTTP responses for all batch parts, including the full HTTP result header (with status code and other potential headers) and an optional result body. The individual batch parts in the result are seperated using the same boundary value as specified in the request. <br><br>The order of batch parts in the response will be the same as in the original client request. Client can additionally use the <em>Content-Id</em> MIME header in a batch part to define an individual id for each batch part. The server will return this id is the batch part responses, too. <br><br>",
"summary": "executes a batch request",
"httpMethod": "POST",
"examples": "<br><br><pre><code class=\"json\" >unix> curl -X POST --header 'Content-Type: multipart/form-data; boundary=SomeBoundaryValue' --data @- --dump - http://localhost:8529/_api/batch\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: myId1\r\n\r\nGET /_api/version HTTP/1.1\r\n\r\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: myId2\r\n\r\nDELETE /_api/collection/products HTTP/1.1\r\n\r\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: someId\r\n\r\nPOST /_api/collection/products HTTP/1.1\r\n\r\n{ \"name\": \"products\" }\r\n\r\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: nextId\r\n\r\nGET /_api/collection/products/figures HTTP/1.1\r\n\r\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: otherId\r\n\r\nDELETE /_api/collection/products HTTP/1.1\r\n--SomeBoundaryValue--\r\n\n\nHTTP/1.1 200 OK\ncontent-type: multipart/form-data; boundary=SomeBoundaryValue\nx-arango-errors: 1\n\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: myId1\r\n\r\nHTTP/1.1 200 OK\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: 41\r\n\r\n{\"server\":\"arango\",\"version\":\"1.4.devel\"}\r\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: myId2\r\n\r\nHTTP/1.1 404 Not Found\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: 88\r\n\r\n{\"error\":true,\"code\":404,\"errorNum\":1203,\"errorMessage\":\"unknown collection 'products'\"}\r\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: someId\r\n\r\nHTTP/1.1 200 OK\r\nlocation: /_db/_system/_api/collection/products\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: 137\r\n\r\n{\"id\":\"330952107\",\"name\":\"products\",\"waitForSync\":false,\"isVolatile\":false,\"isSystem\":false,\"status\":3,\"type\":2,\"error\":false,\"code\":200}\r\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: nextId\r\n\r\nHTTP/1.1 200 OK\r\nlocation: /_db/_system/_api/collection/products/figures\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: 526\r\n\r\n{\"id\":\"330952107\",\"name\":\"products\",\"doCompact\":true,\"isVolatile\":false,\"isSystem\":false,\"journalSize\":1048576,\"keyOptions\":{\"type\":\"traditional\",\"allowUserKeys\":true},\"waitForSync\":false,\"count\":0,\"figures\":{\"alive\":{\"count\":0,\"size\":0},\"dead\":{\"count\":0,\"size\":0,\"deletion\":0},\"datafiles\":{\"count\":0,\"fileSize\":0},\"journals\":{\"count\":0,\"fileSize\":0},\"compactors\":{\"count\":0,\"fileSize\":0},\"shapefiles\":{\"count\":1,\"fileSize\":2097152},\"shapes\":{\"count\":6},\"attributes\":{\"count\":0}},\"status\":3,\"type\":2,\"error\":false,\"code\":200}\r\n--SomeBoundaryValue\r\nContent-Type: application/x-arango-batchpart\r\nContent-Id: otherId\r\n\r\nHTTP/1.1 200 OK\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: 43\r\n\r\n{\"id\":\"330952107\",\"error\":false,\"code\":200}\r\n--SomeBoundaryValue--\n\n</code></pre><br>",
"nickname": "executesABatchRequest"
}
],
"path": "/_api/batch"
}
]
}