From 90aa185711281144d1466c4c559c96c99ec98f7b Mon Sep 17 00:00:00 2001
From: Spencer Alger <spencer@spenceralger.com>
Date: Fri, 17 Jan 2014 15:50:06 -0700
Subject: [PATCH] added notes to the API docs regarding the two API versions,
 and a warning to the config docs. Also updated the client tests to work with
 the new default

---
 docs/api_methods.asciidoc                   |  3 ++-
 docs/api_methods_0_90.asciidoc              | 17 ++++++++++++++
 docs/configuration.asciidoc                 |  5 ++++-
 scripts/generate/templates/api_methods.tmpl | 15 ++++++++++---
 src/lib/client.js                           |  1 +
 test/unit/test_client.js                    | 25 ++++++++++++---------
 6 files changed, 51 insertions(+), 15 deletions(-)

diff --git a/docs/api_methods.asciidoc b/docs/api_methods.asciidoc
index 225b97618..ad5bb75ec 100644
--- a/docs/api_methods.asciidoc
+++ b/docs/api_methods.asciidoc
@@ -1,6 +1,7 @@
 [[api-reference]]
-== API
+== 1.0 API
 
+NOTE: At this time, you must opt into the 1.0 API by setting the `apiVerion` config parameter.
 
 [[api-bulk]]
 === `bulk`
diff --git a/docs/api_methods_0_90.asciidoc b/docs/api_methods_0_90.asciidoc
index dd83f1627..e8a5c7d37 100644
--- a/docs/api_methods_0_90.asciidoc
+++ b/docs/api_methods_0_90.asciidoc
@@ -1,6 +1,7 @@
 [[api-reference-0-90]]
 == 0.90 API
 
+NOTE: This is currently the default API, but with the upcoming release of Elasticsearch 1.0 that will change. We recommend setting the `apiVersion` config param when you instantiate your client to make sure that the API does not change when the default does.
 
 [[api-bulk-0-90]]
 === `bulk`
@@ -2142,6 +2143,22 @@ client.percolate({
 `type`::
 `String` -- The document type
 
+[[api-ping-0-90]]
+=== `ping`
+
+[source,js]
+--------
+client.ping([params, [callback]])
+--------
+
+// no description
+
+The default method is `HEAD` and the usual <<api-conventions,params and return values>> apply. See http://www.elasticsearch.org/guide/[the elasticsearch docs] for more about this method.
+
+// no examples
+
+
+
 [[api-scroll-0-90]]
 === `scroll`
 
diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc
index a88d92324..3d8a3a008 100644
--- a/docs/configuration.asciidoc
+++ b/docs/configuration.asciidoc
@@ -45,10 +45,13 @@ Default in Node:::
 
 `apiVersion`[[config-api-version]]:: `String` -- Change the API that they client provides, specify the major version of the Elasticsearch nodes you will be connecting to.
 
-Default ::: `"master"`
+WARNING: This default will track the latest version of Elasticsearch, and is only intended to be used durring develoopment. It is highly recommended that you set this parameter in all code that is headed to production.
+
+Default ::: `"0.90"`
 
 Options :::
   * `"master"`
+  * `"1.0"`
   * `"0.90"`
 
 
diff --git a/scripts/generate/templates/api_methods.tmpl b/scripts/generate/templates/api_methods.tmpl
index f857b603e..f0c09ca84 100644
--- a/scripts/generate/templates/api_methods.tmpl
+++ b/scripts/generate/templates/api_methods.tmpl
@@ -1,6 +1,15 @@
-[[api-reference<%= branchSuffix %>]]
-== <%= branch === 'master' ? '' : branch + ' ' %>API
-<%
+[[api-reference<%= branchSuffix %>]]<%
+
+if ( branch === 'master' ) {%>
+== 1.0 API
+
+NOTE: At this time, you must opt into the 1.0 API by setting the `apiVerion` config parameter.<%
+} else {%>
+== 0.90 API
+
+NOTE: This is currently the default API, but with the upcoming release of Elasticsearch 1.0 that will change. We recommend setting the `apiVersion` config param when you instantiate your client to make sure that the API does not change when the default does.<%
+}
+
 _.each(actions, function (action) {
 %>
 
diff --git a/src/lib/client.js b/src/lib/client.js
index 9f44bedc1..9edbb24de 100755
--- a/src/lib/client.js
+++ b/src/lib/client.js
@@ -75,5 +75,6 @@ function Client(config) {
 
 Client.apis = {
   'master': require('./api'),
+  '1.0': require('./api'),
   '0.90': require('./api_0_90')
 };
\ No newline at end of file
diff --git a/test/unit/test_client.js b/test/unit/test_client.js
index 3ac64ab39..d926c3d28 100644
--- a/test/unit/test_client.js
+++ b/test/unit/test_client.js
@@ -1,32 +1,37 @@
 describe('Client instances creation', function () {
   var es = require('../../src/elasticsearch');
   var api = require('../../src/lib/api');
+  var api090 = require('../../src/lib/api_0_90');
   var expect = require('expect.js');
   var client;
 
   beforeEach(function () {
-    if (client) {
-      client.close();
-    }
     client = new es.Client();
   });
 
+  afterEach(function () {
+    client.close();
+  });
+
   it('throws an error linking to the es module when you try to instanciate the exports', function () {
     var Es = es;
     expect(function () {
-      var client = new Es();
+      var c = new Es();
     }).to.throwError(/previous "elasticsearch" module/);
   });
 
-  it('Succeeds even not called with new', function () {
-    var client = es.Client();
-    expect(client.bulk).to.eql(api.bulk);
-    expect(client.cluster.nodeStats).to.eql(api.cluster.prototype.nodeStats);
+  it('inherits the 0.90 API by default', function () {
+    expect(client.bulk).to.eql(api090.bulk);
+    expect(client.cluster.nodeStats).to.eql(api090.cluster.prototype.nodeStats);
   });
 
-  it('inherits the api', function () {
+  it('inherits the master API when specified', function () {
+    client.close();
+    client = es.Client({
+      apiVersion: 'master'
+    });
     expect(client.bulk).to.eql(api.bulk);
-    expect(client.cluster.nodeStats).to.eql(api.cluster.prototype.nodeStats);
+    expect(client.nodes.stats).to.eql(api.nodes.prototype.stats);
   });
 
   it('closing the client causes it\'s transport to be closed', function () {