diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt
index 63148a4f54..30debb7b25 100644
--- a/Documentation/rest-api.txt
+++ b/Documentation/rest-api.txt
@@ -8,6 +8,7 @@ supporting some ad-hoc scripting use cases.
 Protocol Details
 ----------------
 
+[[authentication]]
 Authentication
 ~~~~~~~~~~~~~~
 By default all REST endpoints assume anonymous access and filter
@@ -20,6 +21,7 @@ Gerrit by default uses HTTP digest authentication. To authenticate,
 prefix the endpoint URL with `/a/`. For example to authenticate to
 `/projects/` request URL `/a/projects/`.
 
+[[output]]
 Output Format
 ~~~~~~~~~~~~~
 Most APIs return text format by default. JSON can be requested
@@ -147,6 +149,7 @@ and accepts the same options as query parameters.
   }
 ----
 
+[[suggest-projects]]
 The `/projects/` URL also accepts a prefix string as part of the URL.
 This limits the results to those projects that start with the specified
 prefix.
diff --git a/ReleaseNotes/ReleaseNotes-2.5.txt b/ReleaseNotes/ReleaseNotes-2.5.txt
index 22efb808f5..ab75cd0c11 100644
--- a/ReleaseNotes/ReleaseNotes-2.5.txt
+++ b/ReleaseNotes/ReleaseNotes-2.5.txt
@@ -213,3 +213,43 @@ because it was dynamically installed or reloaded by an administrator.
 
 * link:../Documentation/dev-plugins.html#getting-started[Maven
   archetype for creating gerrit plugin projects]
+
+REST API
+~~~~~~~~
+Gerrit now supports a REST like API available over HTTP. The API is
+suitable for automated tools to build upon, as well as supporting some
+ad-hoc scripting use cases.
+
+* link:../Documentation/rest-api.html[Documentation of the REST API]
+
+* Support REST endpoints to
+** link:../Documentation/rest-api.html#changes[query changes]
+** link:../Documentation/rest-api.html#projects[list projects]
+** link:../Documentation/rest-api.html#suggest-projects[suggest
+   projects]
+** link:../Documentation/rest-api.html#accounts_self_capabilities[query
+   the global capabilities of the calling user]
+
+* Support link:../Documentation/rest-api.html#authentication[anonymous
+  and authenticated access] to the REST endpoints
+
+* Support link:../Documentation/rest-api.html#output[JSON output
+  format] for the REST endpoints
+
+The new REST API is used from the Gerrit WebUI.
+
+Some of the methods from the old internal JSON-RPC interface were
+completely replaced by the new REST API and got deleted:
+
+* `ProjectAdminService.visibleProjects(AsyncCallback<ProjectList>)`
+* `ProjectAdminService.suggestParentCandidates(AsyncCallback<List<Project>>)`
+* `ChangeListService.myStarredChangeIds(AsyncCallback<Set<Change.Id>>)`
+* `ChangeListService.allQueryNext(String, String, int, AsyncCallback<SingleListChangeInfo>)`
+* `ChangeListService.allQueryPrev(String, String, int, AsyncCallback<SingleListChangeInfo>)`
+* `ChangeListService.forAccount(Account.Id, AsyncCallback<AccountDashboardInfo>)`
+
+In addition the `/query` API has been deprecated. By default it is
+still available but server administrators may disable it by setting
+the link:../Documentation/config-gerrit.html#site.enableDeprecatedQuery[
+`site.enableDeprecatedQuery`] parameter in the Gerrit config file. This
+allows to enforce tools to move to the new API.