Add restApi.getVersion() method to plugin REST API

Also, documentation and refactoring.

Feature: Issue 8791
Change-Id: I9ac64773d207739052bac6060c83212307d344d8

Documentation/pg-plugin-dev.txt

@@ -289,7 +289,18 @@ Note: TODO
 
 Note: TODO
 
-[plugin-repo]
+[[plugin-rest-api]]
+=== restApi
+`plugin.restApi(opt_prefix)`
+
+.Params:
+- (optional) URL prefix, for easy switching into plugin URL space,
+  e.g. `changes/1/revisions/1/cookbook~say-hello`
+
+.Returns:
+- Instance of link:pg-plugin-rest-api.html[GrPluginRestApi].
+
+[[plugin-repo]]
 === repo
 `plugin.repo()`
 

Documentation/pg-plugin-rest-api.txt

@@ -0,0 +1,104 @@
+= Gerrit Code Review - Repo admin customization API
+
+This API is provided by link:pg-plugin-dev.html#plugin-rest-api[plugin.restApi()]
+and provides interface for Gerrit REST API.
+
+== getLoggedIn
+`repoApi.getLoggedIn()`
+
+Get user logged in status.
+
+.Params
+- None
+
+.Returns
+- Promise<boolean>
+
+== getVersion
+`repoApi.getVersion()`
+
+Get server version.
+
+.Params
+- None
+
+.Returns
+- Promise<string>
+
+== get
+`repoApi.get(url)`
+
+Issues a GET REST API call to the URL, returns Promise that is resolved to
+parsed response on success. Returned Promise is rejected on network error.
+
+.Params
+- *url* String URL without base path or plugin prefix.
+
+.Returns
+- Promise<Object> Parsed response.
+
+== post
+`repoApi.post(url, opt_payload)`
+
+Issues a POST REST API call to the URL, returns Promise that is resolved to
+parsed response on success. Returned Promise is rejected on network error.
+
+.Params
+- *url* String URL without base path or plugin prefix.
+- *opt_payload* (optional) Object Payload to be sent with the request.
+
+.Returns
+- Promise<Object> Parsed response.
+
+== put
+`repoApi.put(url, opt_payload)`
+
+Issues a PUT REST API call to the URL, returns Promise that is resolved to
+parsed response on success. Returned Promise is rejected on network error.
+
+.Params
+- *url* String URL without base path or plugin prefix.
+- *opt_payload* (optional) Object Payload to be sent with the request.
+
+.Returns
+- Promise<Object> Parsed response.
+
+== delete
+`repoApi.delete(url)`
+
+Issues a DELETE REST API call to the URL, returns Promise that is resolved to
+parsed response on HTTP 204, and rejected otherwise.
+
+.Params
+- *url* String URL without base path or plugin prefix.
+
+.Returns
+- Promise<Response> Fetch API's Response object.
+
+== send
+`repoApi.send(method, url, opt_payload)`
+
+Send payload and parse the response, if request succeeds. Returned Promise is
+rejected with detailed message or HTTP error code on network error.
+
+.Params
+- *method* String HTTP method.
+- *url* String URL without base path or plugin prefix.
+- *opt_payload* (optional) Object Respected for POST and PUT only.
+
+.Returns
+- Promise<Object> Parsed response.
+
+== fetch
+`repoApi.fetch(method, url, opt_payload)`
+
+Send payload and return native Response. This method is for low-level access, to
+implement custom error handling and parsing.
+
+.Params
+- *method* String HTTP method.
+- *url* String URL without base path or plugin prefix.
+- *opt_payload* (optional) Object Respected for POST and PUT only.
+
+.Returns
+- Promise<Response> Fetch API's Response object.

polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-rest-api.js

@@ -17,13 +17,25 @@
 (function(window) {
   'use strict';
 
+  let restApi;
+
+  function getRestApi() {
+    if (!restApi) {
+      restApi = document.createElement('gr-rest-api-interface');
+    }
+    return restApi;
+  }
+
   function GrPluginRestApi(opt_prefix) {
     this.opt_prefix = opt_prefix || '';
-    this._restApi = document.createElement('gr-rest-api-interface');
   }
 
   GrPluginRestApi.prototype.getLoggedIn = function() {
-    return this._restApi.getLoggedIn();
+    return getRestApi().getLoggedIn();
+  };
+
+  GrPluginRestApi.prototype.getVersion = function() {
+    return getRestApi().getVersion();
   };
 
   /**
@@ -34,7 +46,7 @@
    * @return {!Promise}
    */
   GrPluginRestApi.prototype.fetch = function(method, url, opt_payload) {
-    return this._restApi.send(method, this.opt_prefix + url, opt_payload);
+    return getRestApi().send(method, this.opt_prefix + url, opt_payload);
   };
 
   /**
@@ -55,7 +67,7 @@
           }
         });
       } else {
-        return this._restApi.getResponseObject(response);
+        return getRestApi().getResponseObject(response);
       }
     });
   };

polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-rest-api_test.html

@@ -30,20 +30,23 @@ limitations under the License.
     let sandbox;
     let getResponseObjectStub;
     let sendStub;
+    let restApiStub;
 
     setup(() => {
       sandbox = sinon.sandbox.create();
       getResponseObjectStub = sandbox.stub().returns(Promise.resolve());
       sendStub = sandbox.stub().returns(Promise.resolve({status: 200}));
-      stub('gr-rest-api-interface', {
-        getAccount() {
-          return Promise.resolve({name: 'Judy Hopps'});
-        },
+      restApiStub = {
+        getAccount: () => Promise.resolve({name: 'Judy Hopps'}),
         getResponseObject: getResponseObjectStub,
-        send(...args) {
-          return sendStub(...args);
-        },
-      });
+        send: sendStub,
+        getLoggedIn: sandbox.stub(),
+        getVersion: sandbox.stub(),
+      };
+      stub('gr-rest-api-interface', Object.keys(restApiStub).reduce((a, k) => {
+        a[k] = (...args) => restApiStub[k](...args);
+        return a;
+      }, {}));
       Gerrit._setPluginsCount(1);
       Gerrit.install(p => { plugin = p; }, '0.1',
           'http://test.com/plugins/testplugin/static/test.js');
@@ -121,5 +124,21 @@ limitations under the License.
         assert.equal('text', err);
       });
     });
+
+    test('getLoggedIn', () => {
+      restApiStub.getLoggedIn.returns(Promise.resolve(true));
+      return instance.getLoggedIn().then(result => {
+        assert.isTrue(restApiStub.getLoggedIn.calledOnce);
+        assert.isTrue(result);
+      });
+    });
+
+    test('getConfig', () => {
+      restApiStub.getVersion.returns(Promise.resolve('foo bar'));
+      return instance.getVersion().then(result => {
+        assert.isTrue(restApiStub.getVersion.calledOnce);
+        assert.equal(result, 'foo bar');
+      });
+    });
   });
 </script>