fixed documentation

Conflicts: Documentation/Scripts/generateSwaggerApi.py
2015-04-03 13:16:41 +02:00 · 2015-04-03 13:16:41 +02:00 · 92c8dc9429
parent 270397da32
commit 92c8dc9429
2 changed files with 246 additions and 7 deletions
--- a/Documentation/Scripts/generateSwaggerApi.py
+++ b/Documentation/Scripts/generateSwaggerApi.py
@ -45,8 +45,8 @@ files = {
  "js/actions/api-aqlfunction.js" : "aqlfunction",
  "arangod/RestHandler/RestBatchHandler.cpp" : "batch",
  "js/actions/_api/collection/app.js" : "collection",
-  "js/actions/_admin/database/app.js" : "database",
  "arangod/RestHandler/RestCursorHandler.cpp" : "cursor",
+  "js/actions/api-database.js" : "database",
  "arangod/RestHandler/RestDocumentHandler.cpp" : "document",
  "arangod/RestHandler/RestEdgeHandler.cpp" : "edge",
  "arangod/RestHandler/RestExportHandler.cpp" : "export",
--- a/arangod/RestHandler/RestQueryHandler.cpp
+++ b/arangod/RestHandler/RestQueryHandler.cpp
@ -109,7 +109,45 @@ HttpHandler::status_t RestQueryHandler::execute () {
 // -----------------------------------------------------------------------------

 ////////////////////////////////////////////////////////////////////////////////
-/// @brief returns the list of properties
+/// @startDocuBlock GetApiQueryProperties
+/// @brief returns the configuration for the AQL query tracking
+///
+/// @RESTHEADER{GET /_api/query/properties, Returns the properties for the AQL query tracking}
+///
+/// Returns the current query tracking configuration. The configuration is a
+/// JSON object with the following properties:
+/// 
+/// - *enabled*: if set to *true*, then queries will be tracked. If set to 
+///   *false*, neither queries nor slow queries will be tracked.
+///
+/// - *trackSlowQueries*: if set to *true*, then slow queries will be tracked
+///   in the list of slow queries if their runtime exceeds the value set in 
+///   *slowQueryThreshold*. In order for slow queries to be tracked, the *enabled*
+///   property must also be set to *true*.
+/// 
+/// - *maxSlowQueries*: the maximum number of slow queries to keep in the list
+///   of slow queries. If the list of slow queries is full, the oldest entry in
+///   it will be discarded when additional slow queries occur.
+///
+/// - *slowQueryThreshold*: the threshold value for treating a query as slow. A
+///   query with a runtime greater or equal to this threshold value will be
+///   put into the list of slow queries when slow query tracking is enabled.
+///   The value for *slowQueryThreshold* is specified in seconds.
+///
+/// - *maxQueryStringLength*: the maximum query string length to keep in the
+///   list of queries. Query strings can have arbitrary lengths, and this property
+///   can be used to save memory in case very long query strings are used. The
+///   value is specified in bytes.
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// Is returned when the list of queries can be retrieved successfully.
+///
+/// @RESTRETURNCODE{400}
+/// The server will respond with *HTTP 400* in case of a malformed request,
+///
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////

 bool RestQueryHandler::readQueryProperties () {
@ -145,7 +183,67 @@ bool RestQueryHandler::readQueryProperties () {
 }

 ////////////////////////////////////////////////////////////////////////////////
-/// @brief returns the list of slow queries
+/// @startDocuBlock GetApiQueryCurrent
+/// @brief returns a list of currently running AQL queries
+///
+/// @RESTHEADER{GET /_api/query/current, Returns the currently running AQL queries}
+///
+/// Returns an array containing the AQL queries currently running in the selected
+/// database. Each query is a JSON object with the following attributes:
+///
+/// - *id*: the query's id
+///
+/// - *query*: the query string (potentially truncated)
+///
+/// - *started*: the date and time when the query was started
+///
+/// - *runTime*: the query's run time up to the point the list of queries was
+///   queried
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// Is returned when the list of queries can be retrieved successfully.
+///
+/// @RESTRETURNCODE{400}
+/// The server will respond with *HTTP 400* in case of a malformed request,
+///
+/// @endDocuBlock
+////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+/// @startDocuBlock GetApiQuerySlow
+/// @brief returns a list of slow running AQL queries
+///
+/// @RESTHEADER{GET /_api/query/slow, Returns the list of slow AQL queries}
+///
+/// Returns an array containing the last AQL queries that exceeded the slow 
+/// query threshold in the selected database. 
+/// The maximum amount of queries in the list can be controlled by setting
+/// the query tracking property `maxSlowQueries`. The threshold for treating
+/// a query as *slow* can be adjusted by setting the query tracking property
+/// `slowQueryThreshold`.
+///
+/// Each query is a JSON object with the following attributes:
+///
+/// - *id*: the query's id
+///
+/// - *query*: the query string (potentially truncated)
+///
+/// - *started*: the date and time when the query was started
+///
+/// - *runTime*: the query's run time up to the point the list of queries was
+///   queried
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// Is returned when the list of queries can be retrieved successfully.
+///
+/// @RESTRETURNCODE{400}
+/// The server will respond with *HTTP 400* in case of a malformed request,
+///
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////

 bool RestQueryHandler::readQuery (bool slow) {
@ -219,7 +317,20 @@ bool RestQueryHandler::readQuery () {
 }

 ////////////////////////////////////////////////////////////////////////////////
-/// @brief removes the slow log
+/// @startDocuBlock DeleteApiQuerySlow
+/// @brief clears the list of slow AQL queries
+///
+/// @RESTHEADER{DELETE /_api/query/slow, Clears the list of slow AQL queries}
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{204}
+/// The server will respond with *HTTP 200* when the list of queries was
+/// cleared successfully.
+///
+/// @RESTRETURNCODE{400}
+/// The server will respond with *HTTP 400* in case of a malformed request.
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////

 bool RestQueryHandler::deleteQuerySlow () {
@ -239,7 +350,32 @@ bool RestQueryHandler::deleteQuerySlow () {
 }

 ////////////////////////////////////////////////////////////////////////////////
-/// @brief interrupts a named query
+/// @startDocuBlock DeleteApiQueryKill
+/// @brief kills an AQL query
+///
+/// @RESTHEADER{DELETE /_api/query/{query-id}, Kills a running AQL query}
+///
+/// @RESTURLPARAMETERS
+///
+/// @RESTURLPARAM{query-id,string,required}
+/// The id of the query.
+///
+/// Kills a running query. The query will be terminated at the next cancellation
+/// point.
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// The server will respond with *HTTP 200* when the query was still running when
+/// the kill request was executed and the query's kill flag was set.
+///
+/// @RESTRETURNCODE{400}
+/// The server will respond with *HTTP 400* in case of a malformed request.
+///
+/// @RESTRETURNCODE{404}
+/// The server will respond with *HTTP 404* when no query with the specified
+/// id was found.
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////

 bool RestQueryHandler::deleteQuery (const string& name) {
@ -290,7 +426,52 @@ bool RestQueryHandler::deleteQuery () {
 }

 ////////////////////////////////////////////////////////////////////////////////
-/// @brief changes the settings
+/// @startDocuBlock PutApiQueryProperties
+/// @brief changes the configuration for the AQL query tracking
+///
+/// @RESTHEADER{PUT /_api/query/properties, Changes the properties for the AQL query tracking}
+///
+/// @RESTBODYPARAM{properties,json,required}
+/// The properties for query tracking in the current database. 
+///
+/// The properties need to be passed in the attribute *properties* in the body
+/// of the HTTP request. *properties* needs to be a JSON object with the following
+/// properties:
+/// 
+/// - *enabled*: if set to *true*, then queries will be tracked. If set to 
+///   *false*, neither queries nor slow queries will be tracked.
+///
+/// - *trackSlowQueries*: if set to *true*, then slow queries will be tracked
+///   in the list of slow queries if their runtime exceeds the value set in 
+///   *slowQueryThreshold*. In order for slow queries to be tracked, the *enabled*
+///   property must also be set to *true*.
+/// 
+/// - *maxSlowQueries*: the maximum number of slow queries to keep in the list
+///   of slow queries. If the list of slow queries is full, the oldest entry in
+///   it will be discarded when additional slow queries occur.
+///
+/// - *slowQueryThreshold*: the threshold value for treating a query as slow. A
+///   query with a runtime greater or equal to this threshold value will be
+///   put into the list of slow queries when slow query tracking is enabled.
+///   The value for *slowQueryThreshold* is specified in seconds.
+///
+/// - *maxQueryStringLength*: the maximum query string length to keep in the
+///   list of queries. Query strings can have arbitrary lengths, and this property
+///   can be used to save memory in case very long query strings are used. The
+///   value is specified in bytes.
+///
+/// After the properties have been changed, the current set of properties will
+/// be returned in the HTTP response.
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// Is returned if the properties were changed successfully.
+///
+/// @RESTRETURNCODE{400}
+/// The server will respond with *HTTP 400* in case of a malformed request,
+///
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////

 bool RestQueryHandler::replaceProperties () {
@ -365,7 +546,65 @@ bool RestQueryHandler::replaceProperties () {
 }

 ////////////////////////////////////////////////////////////////////////////////
-/// @brief parses a query
+/// @startDocuBlock JSF_post_api_query
+/// @brief parse an AQL query and return information about it
+///
+/// @RESTHEADER{POST /_api/query, Parse an AQL query}
+///
+/// @RESTBODYPARAM{query,json,required}
+/// To validate a query string without executing it, the query string can be
+/// passed to the server via an HTTP POST request.
+///
+/// The query string needs to be passed in the attribute *query* of a JSON
+/// object as the body of the POST request.
+///
+/// @RESTRETURNCODES
+///
+/// @RESTRETURNCODE{200}
+/// If the query is valid, the server will respond with *HTTP 200* and
+/// return the names of the bind parameters it found in the query (if any) in
+/// the *bindVars* attribute of the response. It will also return an array
+/// of the collections used in the query in the *collections* attribute. 
+/// If a query can be parsed successfully, the *ast* attribute of the returned
+/// JSON will contain the abstract syntax tree representation of the query.
+/// The format of the *ast* is subject to change in future versions of 
+/// ArangoDB, but it can be used to inspect how ArangoDB interprets a given
+/// query. Note that the abstract syntax tree will be returned without any
+/// optimizations applied to it.
+///
+/// @RESTRETURNCODE{400}
+/// The server will respond with *HTTP 400* in case of a malformed request,
+/// or if the query contains a parse error. The body of the response will
+/// contain the error details embedded in a JSON object.
+///
+/// @EXAMPLES
+///
+/// Valid query:
+///
+/// @EXAMPLE_ARANGOSH_RUN{RestQueryValid}
+///     var url = "/_api/query";
+///     var body = '{ "query" : "FOR p IN products FILTER p.name == @name LIMIT 2 RETURN p.n" }';
+///
+///     var response = logCurlRequest('POST', url, body);
+///
+///     assert(response.code === 200);
+///
+///     logJsonResponse(response);
+/// @END_EXAMPLE_ARANGOSH_RUN
+///
+/// Invalid query:
+///
+/// @EXAMPLE_ARANGOSH_RUN{RestQueryInvalid}
+///     var url = "/_api/query";
+///     var body = '{ "query" : "FOR p IN products FILTER p.name = @name LIMIT 2 RETURN p.n" }';
+///
+///     var response = logCurlRequest('POST', url, body);
+///
+///     assert(response.code === 400);
+///
+///     logJsonResponse(response);
+/// @END_EXAMPLE_ARANGOSH_RUN
+/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////

 bool RestQueryHandler::parseQuery () {