Document how GWT plugins can make REST calls to the server
Change-Id: I0c00c7b8a58fb3c5d6cba13bc26e343b6d88f210
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt
index c30310d..2c3b2bb 100644
--- a/Documentation/dev-plugins.txt
+++ b/Documentation/dev-plugins.txt
@@ -1236,6 +1236,59 @@
<stylesheet src="hello.css"/>
----
+If a GWT plugin wants to invoke the Gerrit REST API it can use
+`com.google.gerrit.plugin.client.rpc.RestApi` to contruct the URL
+path and to trigger the REST calls.
+
+Example for invoking a Gerrit core REST endpoint:
+
+[source,java]
+----
+new RestApi("projects").id(projectName).view("description")
+ .put("new description", new AsyncCallback<JavaScriptObject>() {
+
+ @Override
+ public void onSuccess(JavaScriptObject result) {
+ // TODO
+ }
+
+ @Override
+ public void onFailure(Throwable caught) {
+ // never invoked
+ }
+});
+----
+
+Example for invoking a REST endpoint defined by a plugin:
+
+[source,java]
+----
+new RestApi("projects").id(projectName).view("myplugin", "myview")
+ .get(new AsyncCallback<JavaScriptObject>() {
+
+ @Override
+ public void onSuccess(JavaScriptObject result) {
+ // TODO
+ }
+
+ @Override
+ public void onFailure(Throwable caught) {
+ // never invoked
+ }
+});
+----
+
+The `onFailure(Throwable)` of the provided callback is never invoked.
+If an error occurs, it is shown in an error dialog.
+
+In order to be able to do REST calls the GWT module must inherit
+`com.google.gwt.json.JSON`:
+
+[source,xml]
+----
+<inherits name="com.google.gwt.json.JSON"/>
+----
+
[[http]]
HTTP Servlets
-------------
