Merge pull request #5 from arangodb/arbitrary-apis

Added support for arbitrary APIs. Fixes #4.

Author: pluma

README.md

@@ -148,6 +148,19 @@ Performs a database query using the given *query* and *bindVars*, then passes a
 * *query*: an AQL query string or a [query builder](https://npmjs.org/package/aqb) instance.
 * *bindVars* (optional): an object with the variables to bind the query to.
 
+### Arbitrary HTTP endpoints
+
+#### database.endpoint([path[, headers]])
+
+Returns a new *Endpoint* instance for the given path (relative to the database) that can be used to perform arbitrary HTTP requests.
+
+*Parameter*
+
+* *path* (optional): relative URL of the endpoint.
+* *headers* (optional): default headers that should be send with each request to the endpoint.
+
+If *path* is missing, the endpoint will refer to the base URL of the database.
+
 ## Cursor API
 
 *Cursor* instances provide an abstraction over the HTTP API's limitations. Unless a method explicitly exhausts the cursor, the driver will only fetch as many batches from the server as necessary. Unlike the server-side cursors, *Cursor* instances can also be rewinded.
@@ -202,6 +215,117 @@ Equivalent to *Array.prototype.reduce*.
 
 Rewinds the cursor.
 
+## Endpoint API
+
+*Endpoint* instances provide access for arbitrary HTTP requests. This allows easy access to Foxx apps and other HTTP APIs not covered by the driver itself.
+
+### endpoint.get([path,] [qs,] callback)
+
+Performs a GET request to the given URL and passes the server response to the given callback.
+
+*Parameter*
+
+* *path* (optional): the endpoint-relative URL for the request.
+* *qs* (optional): the query string for the request.
+
+If *path* is missing, the request will be made to the base URL of the endpoint.
+
+If *qs* is an object, it will be translated to a query string.
+
+### endpoint.post([path,] [body, [qs,]] callback)
+
+Performs a POST request to the given URL and passes the server response to the given callback.
+
+*Parameter*
+
+* *path* (optional): the endpoint-relative URL for the request.
+* *body* (optional): the request body for the request.
+* *qs* (optional): the query string for the request.
+
+If *path* is missing, the request will be made to the base URL of the endpoint.
+
+If *body* is an object, it will be converted to JSON.
+
+If *qs* is an object, it will be translated to a query string.
+
+### endpoint.put([path,] [body, [qs,]] callback)
+
+Performs a PUT request to the given URL and passes the server response to the given callback.
+
+*Parameter*
+
+* *path* (optional): the endpoint-relative URL for the request.
+* *body* (optional): the request body for the request.
+* *qs* (optional): the query string for the request.
+
+If *path* is missing, the request will be made to the base URL of the endpoint.
+
+If *body* is an object, it will be converted to JSON.
+
+If *qs* is an object, it will be translated to a query string.
+
+### endpoint.patch([path,] [body, [qs,]] callback)
+
+Performs a PATCH request to the given URL and passes the server response to the given callback.
+
+*Parameter*
+
+* *path* (optional): the endpoint-relative URL for the request.
+* *body* (optional): the request body for the request.
+* *qs* (optional): the query string for the request.
+
+If *path* is missing, the request will be made to the base URL of the endpoint.
+
+If *body* is an object, it will be converted to JSON.
+
+If *qs* is an object, it will be translated to a query string.
+
+### endpoint.delete([path,] [qs,] callback)
+
+Performs a DELETE request to the given URL and passes the server response to the given callback.
+
+*Parameter*
+
+* *path* (optional): the endpoint-relative URL for the request.
+* *qs* (optional): the query string for the request.
+
+If *path* is missing, the request will be made to the base URL of the endpoint.
+
+If *qs* is an object, it will be translated to a query string.
+
+### endpoint.head([path,] [qs,] callback)
+
+Performs a HEAD request to the given URL and passes the server response to the given callback.
+
+*Parameter*
+
+* *path* (optional): the endpoint-relative URL for the request.
+* *qs* (optional): the query string for the request.
+
+If *path* is missing, the request will be made to the base URL of the endpoint.
+
+If *qs* is an object, it will be translated to a query string.
+
+### endpoint.request(opts, callback)
+
+Performs an arbitrary request to the given URL and passes the server response to the given callback.
+
+*Parameter*
+
+* *opts*: an object with the following properties:
+ * *path*: the endpoint-relative URL for the request.
+ * *absolutePath* (optional): whether the *path* is relative to the connection's base URL instead of the database. Default: `false`.
+ * *body* (optional): the request body.
+ * *qs* (optional): the query string.
+ * *headers* (optional): an object with additional HTTP headers to send with the request.
+ * *method* (optional): HTTP method to use. Default: `"GET"`.
+
+If *opts.path* is missing, the request will be made to the base URL of the endpoint.
+
+If *opts.body* is an object, it will be converted to JSON.
+
+If *opts.qs* is an object, it will be translated to a query string.
+
 ## Collection API
 
 ### Getting information about the collection

lib/collection.js

@@ -18,6 +18,7 @@ module.exports = extend(
 
 function BaseCollection(connection, body) {
   this._connection = connection;
+  this._api = this._connection.endpoint('_api');
   extend(this, body);
   delete this.code;
   delete this.error;
@@ -37,7 +38,7 @@ extend(BaseCollection.prototype, {
     }
     if (!callback) callback = noop;
     var self = this;
-    self._connection.get('collection/' + self.name + '/' + path, function (err, body) {
+    self._api.get('collection/' + self.name + '/' + path, function (err, body) {
       if (err) callback(err);
       else {
         if (update) {
@@ -52,7 +53,7 @@ extend(BaseCollection.prototype, {
   _put: function (path, data, update, callback) {
     if (!callback) callback = noop;
     var self = this;
-    self._connection.put('collection/' + self.name + '/' + path, data, function (err, body) {
+    self._api.put('collection/' + self.name + '/' + path, data, function (err, body) {
       if (err) callback(err);
       else {
         if (update) extend(self, body);
@@ -102,7 +103,7 @@ extend(BaseCollection.prototype, {
   drop: function (callback) {
     if (!callback) callback = noop;
     var self = this;
-    self._connection.delete('collection/' + self.name, function (err, body) {
+    self._api.delete('collection/' + self.name, function (err, body) {
       if (err) callback(err);
       else callback(null);
     });
@@ -114,7 +115,7 @@ extend(BaseCollection.prototype, {
     }
     if (!callback) callback = noop;
     opts = extend({}, opts, {collection: this.name});
-    this._connection.put(this._documentPath(documentHandle), data, opts, function (err, body) {
+    this._api.put(this._documentPath(documentHandle), data, opts, function (err, body) {
       if (err) callback(err);
       else callback(null, body);
     });
@@ -126,7 +127,7 @@ extend(BaseCollection.prototype, {
     }
     if (!callback) callback = noop;
     opts = extend({}, opts, {collection: this.name});
-    this._connection.patch(this._documentPath(documentHandle), data, opts, function (err, body) {
+    this._api.patch(this._documentPath(documentHandle), data, opts, function (err, body) {
       if (err) callback(err);
       else callback(null, body);
     });
@@ -138,7 +139,7 @@ extend(BaseCollection.prototype, {
     }
     if (!callback) callback = noop;
     opts = extend({}, opts, {collection: this.name});
-    this._connection.delete(this._documentPath(documentHandle), opts, function (err, body) {
+    this._api.delete(this._documentPath(documentHandle), opts, function (err, body) {
       if (err) callback(err);
       else callback(null);
     });
@@ -149,7 +150,7 @@ extend(BaseCollection.prototype, {
       type = undefined;
     }
     if (!callback) callback = noop;
-    this._connection.get('document', {
+    this._api.get('document', {
       type: type || 'id',
       collection: this.name
     }, function (err, body) {
@@ -171,14 +172,14 @@ extend(DocumentCollection.prototype, {
     if (documentHandle.indexOf('/') === -1) {
       documentHandle = this.name + '/' + documentHandle;
     }
-    this._connection.get('document/' + documentHandle, function (err, body) {
+    this._api.get('document/' + documentHandle, function (err, body) {
       if (err) callback(err);
       else callback(null, body);
     });
   },
   save: function (data, callback) {
     if (!callback) callback = noop;
-    this._connection.post('document/', data, {
+    this._api.post('document/', data, {
       collection: this.name
     }, function (err, body) {
       if (err) callback(err);
@@ -199,14 +200,14 @@ extend(EdgeCollection.prototype, {
     if (documentHandle.indexOf('/') === -1) {
       documentHandle = this.name + '/' + documentHandle;
     }
-    this._connection.get('edge/' + documentHandle, function (err, body) {
+    this._api.get('edge/' + documentHandle, function (err, body) {
       if (err) callback(err);
       else callback(null, body);
     });
   },
   save: function (data, fromId, toId, callback) {
     if (!callback) callback = noop;
-    this._connection.post('edge/', data, {
+    this._api.post('edge/', data, {
       collection: this.name,
       from: fromId,
       to: toId
@@ -217,7 +218,7 @@ extend(EdgeCollection.prototype, {
   },
   _edges: function (vertex, direction, callback) {
     if (!callback) callback = noop;
-    this._connection.get('edges/' + this.name, {
+    this._api.get('edges/' + this.name, {
       vertex: vertex,
       direction: direction
     }, function (err, body) {

lib/connection.js

@@ -6,6 +6,7 @@ var noop = require('./util/noop'),
   querystring = require('querystring'),
   request = require('request'),
   ArangoError = require('./error'),
+  Endpoint = require('./endpoint'),
   jsonMime = /\/(json|javascript)(\W|$)/;
 
 module.exports = Connection;
@@ -28,6 +29,9 @@ Connection.defaults = {
 };
 
 extend(Connection.prototype, {
+  endpoint: function (path) {
+    return new Endpoint(this, path);
+  },
   request: function (opts, callback) {
     if (!callback) callback = noop;
     if (!opts) opts = {};
@@ -39,20 +43,16 @@ extend(Connection.prototype, {
       headers['content-type'] = 'application/json';
     }
 
-    var url = this.config.url + '/_db/' + this.config.databaseName + '/_api/' + opts.path;
-    while (true) {
-      var oldUrl = url;
-      url = url.replace(/\/[^\/]+\/..\//, '/');
-      if (oldUrl === url) break;
-    }
+    var url = this.config.url;
+    if (!opts.absolutePath) url += '/_db/' + this.config.databaseName;
+    url += opts.path ? (opts.path.charAt(0) === '/' ? '' : '/') + opts.path : '';
     if (opts.qs) url += '?' + (typeof opts.qs === 'string' ? opts.qs : querystring.stringify(opts.qs));
 
     request({
       url: url,
       headers: extend(headers, this.config.headers, opts.headers),
       method: (opts.method || 'get').toUpperCase(),
-      body: body,
-      encoding: 'utf-8'
+      body: body
     }, function (err, response, rawBody) {
       if (err) callback(err);
       else if (!response.headers['content-type'].match(jsonMime)) callback(null, rawBody);
@@ -65,59 +65,5 @@ extend(Connection.prototype, {
         catch(e) {callback(e);}
       }
     });
-  },
-  get: function (path, data, callback) {
-    if (typeof data === 'function') {
-      callback = data;
-      data = undefined;
-    }
-    this.request({path: path, qs: data}, callback);
-  },
-  post: function (path, data, qs, callback) {
-    if (typeof qs === 'function') {
-      callback = qs;
-      qs = undefined;
-    }
-    if (typeof data === 'function') {
-      callback = data;
-      data = undefined;
-    }
-    this.request({path: path, body: data, qs: qs, method: 'post'}, callback);
-  },
-  put: function (path, data, qs, callback) {
-    if (typeof qs === 'function') {
-      callback = qs;
-      qs = undefined;
-    }
-    if (typeof data === 'function') {
-      callback = data;
-      data = undefined;
-    }
-    this.request({path: path, body: data, qs: qs, method: 'put'}, callback);
-  },
-  patch: function (path, data, qs, callback) {
-    if (typeof qs === 'function') {
-      callback = qs;
-      qs = undefined;
-    }
-    if (typeof data === 'function') {
-      callback = data;
-      data = undefined;
-    }
-    this.request({path: path, body: data, qs: qs, method: 'patch'}, callback);
-  },
-  delete: function (path, data, callback) {
-    if (typeof data === 'function') {
-      callback = data;
-      data = undefined;
-    }
-    this.request({path: path, qs: data, method: 'delete'}, callback);
-  },
-  head: function (path, data, callback) {
-    if (typeof data === 'function') {
-      callback = data;
-      data = undefined;
-    }
-    this.request({path: path, qs: data, method: 'head'}, callback);
   }
 });

lib/cursor.js

@@ -9,6 +9,7 @@ module.exports = ArrayCursor;
 function ArrayCursor(connection, body) {
   this.extra = body.extra;
   this._connection = connection;
+  this._api = this._connection.endpoint('_api');
   this._result = body.result;
   this._hasMore = Boolean(body.hasMore);
   this._id = body.id;
@@ -30,7 +31,7 @@ extend(ArrayCursor.prototype, {
     var self = this;
     if (!self._hasMore) callback(null, self);
     else {
-      self._connection.put('cursor/' + this._id, function (err, body) {
+      self._api.put('cursor/' + this._id, function (err, body) {
         if (err) callback(err);
         else {
           self._result.push.apply(self._result, body.result);