issue #59: added documentation for import api

Doxygen/Examples.ArangoDB/api-import-documents

@@ -0,0 +1,10 @@
+curl --data-binary @- -X POST --dump - "http://localhost:8529/_api/import?type=documents&collection=test&createCollection=true"
+{ "name" : "test", "gender" : "male", "age" : 39 }
+{ "type" : "bird", "name" : "robin" }
+
+HTTP/1.1 201 Created
+server: triagens GmbH High-Performance HTTP Server
+connection: Keep-Alive
+content-type: application/json; charset=utf-8
+
+{"error":false,"created":2,"errors":0}

Doxygen/Examples.ArangoDB/api-import-headers

@@ -0,0 +1,11 @@
+curl --data-binary @- -X POST --dump - "http://localhost:8529/_api/import?collection=test&createCollection=true"
+[ "firstName", "lastName", "age", "gender" ]
+[ "Joe", "Public", 42, "male" ]
+[ "Jane", "Doe", 31, "female" ]
+
+HTTP/1.1 201 Created
+server: triagens GmbH High-Performance HTTP Server
+connection: Keep-Alive
+content-type: application/json; charset=utf-8
+
+{"error":false,"created":2,"errors":0}

Makefile.files

@@ -88,6 +88,7 @@ WIKI = \
 	Home \
 	HttpCollection \
 	HttpCursor \
+	HttpImport \
 	HttpIndex \
 	HttpInterface \
 	HttpQueries \

arangod/Documentation/api-import.dox

@@ -0,0 +1,114 @@
+////////////////////////////////////////////////////////////////////////////////
+/// @brief over the wire protocol
+///
+/// @file
+///
+/// DISCLAIMER
+///
+/// Copyright 2012 triagens GmbH, Cologne, Germany
+///
+/// Licensed under the Apache License, Version 2.0 (the "License");
+/// you may not use this file except in compliance with the License.
+/// You may obtain a copy of the License at
+///
+///     http://www.apache.org/licenses/LICENSE-2.0
+///
+/// Unless required by applicable law or agreed to in writing, software
+/// distributed under the License is distributed on an "AS IS" BASIS,
+/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+/// See the License for the specific language governing permissions and
+/// limitations under the License.
+///
+/// Copyright holder is triAGENS GmbH, Cologne, Germany
+///
+/// @author Jan Steemann
+/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
+////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+/// @page HttpImportTOC
+///
+/// <ul>
+///  <li>@ref HttpImport
+///   <ul>
+///    <li>@ref HttpImportSelfContained
+///    </li>
+///    <li>@ref HttpImportHeaderData
+///    </li>
+///   </ul>
+///  </li>
+/// </ul>
+////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+/// @page HttpImport HTTP Interface for bulk imports
+///
+/// ArangoDB provides an HTTP interface to import multiple documents at once 
+/// into a collection. This is known as a bulk import.
+///
+/// @EMBEDTOC{HttpImportTOC}
+///
+/// The data uploaded must be provided in JSON format. There are two mechanisms
+/// to import the data:
+/// - self-contained documents: in this case, each document contains all 
+///   attribute names and values. Attribute names may be completely different
+///   among the documents uploaded
+/// - attribute names plus document data: in this case, the first document must 
+///   be a JSON list containing the attribute names of the documents that follow.
+///   The following documents must be lists containing only the document data.
+///   Data will be mapped to the attribute names by attribute positions.
+///
+/// The endpoint address is @LIT{/_api/import} for both input mechanisms. 
+/// Data must be sent to this URL using an HTTP POST request. The data to import
+/// must be contained in the body of the POST request.
+/// 
+/// The @LIT{collection} URL parameter must be used to specify the target collection
+/// for the import. The optional URL parameter @LIT{createCollection} can be used
+/// to create a non-existing collection during the import. If not used, importing
+/// data into a non-existing collection will produce an error.
+///
+/// @section HttpImportSelfContained Importing self-contained documents
+///////////////////////////////////////////////////////////////////////
+///
+/// This import method allows uploading self-contained JSON documents. The
+/// documents must be uploaded in the body of the HTTP POST request. Each line
+/// of the body will be interpreted as one stand-alone document. Empty lines
+/// in the body are allowed and will be skipped.
+/// 
+/// To use this method, the @LIT{type} URL parameter should be set to @LIT{documents}.
+///
+/// @EXAMPLES
+///
+/// @verbinclude api-import-documents
+///
+/// The server will respond with an HTTP 201 if everything went well. The number
+/// of documents imported will be returned in the @LIT{created} attribute of
+/// the response. If any documents were skipped or incorrectly formatted, this 
+/// will be returned in the @LIT{errors} attribute.
+///
+/// @section HttpImportHeaderData Importing headers and values
+//////////////////////////////////////////////////////////////
+///
+/// When using this type of import, the attribute names of the documents to be
+/// imported are specified separate from the actual document value data.
+/// The first line of the HTTP POST request body must be a JSON list containing 
+/// the attribute names for the documents that follow.
+/// The following lines are interpreted as the document data. Each document must
+/// be a JSON list of values. No attribute names are needed or allowed in this
+/// data section.
+///
+/// @EXAMPLES
+///
+/// @verbinclude api-import-headers
+///
+/// The server will again respond with an HTTP 201 if everything went well. The 
+/// number of documents imported will be returned in the @LIT{created} attribute of
+/// the response. If any documents were skipped or incorrectly formatted, this 
+/// will be returned in the @LIT{errors} attribute.
+////////////////////////////////////////////////////////////////////////////////
+
+// Local Variables:
+// mode: c++
+// mode: outline-minor
+// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)"
+// End:

arangod/Documentation/implementor-manual.dox

@@ -41,6 +41,7 @@
 ///  <li>@ref HttpCollection</li>
 ///  <li>@ref HttpIndex</li>
 ///  <li>@ref HttpSystem</li>
+///  <li>@ref HttpImport</li>
 ///  <li>@ref ArangoErrors</li>
 ///  <li>@ref IndexSkiplist</li>
 ///  <li>@ref Glossary</li>
@@ -65,6 +66,9 @@
 ///   @copydetails HttpIndexTOC
 ///   @copydetails HttpSystemTOC
 ///  </li>
+///  <li>Interface for bulk imports
+///   @copydetails HttpImportTOC
+///  </li>
 ///  <li>Advanced Topics
 ///   <ul>
 ///    <li>@ref ArangoErrors</li>