Document that onFailure() for REST calls from plugin is never invoked
A change to show case this problem was pushed for the cookbook plugin
[1].
[1] https://gerrit-review.googlesource.com/#/c/68850
Change-Id: I17abca24018c4512025abbcb0c691da9bd18c4f6
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt
index dde55a2..081f370 100644
--- a/Documentation/dev-plugins.txt
+++ b/Documentation/dev-plugins.txt
@@ -1952,6 +1952,40 @@
Disabled plugins can be re-enabled using the
link:cmd-plugin-enable.html[plugin enable] command.
+== Known issues and bugs
+
+=== Error handling in UI when using the REST API
+
+When a plugin invokes a REST endpoint in the UI, it provides an
+`AsyncCallback` to handle the result. At the moment the
+`onFailure(Throwable)` of the callback is never invoked, even if there
+is an error. Errors are always handled by the Gerrit core UI which
+shows the error dialog. This means currently plugins cannot do any
+error handling and e.g. ignore expected errors.
+
+In the following example the REST endpoint would return '404 Not Found'
+if there is no HTTP password and the Gerrit core UI would display an
+error dialog for this. However having no HTTP password is not an error
+and the plugin may like to handle this case.
+
+[source,java]
+----
+new RestApi("accounts").id("self").view("password.http")
+ .get(new AsyncCallback<NativeString>() {
+
+ @Override
+ public void onSuccess(NativeString httpPassword) {
+ // TODO
+ }
+
+ @Override
+ public void onFailure(Throwable caught) {
+ // never invoked
+ }
+});
+----
+
+
== SEE ALSO
* link:js-api.html[JavaScript API]
