diff --git a/docs/reference/migration/migrate_5_0/java.asciidoc b/docs/reference/migration/migrate_5_0/java.asciidoc
index 59f0b1c15e2..df526740f33 100644
--- a/docs/reference/migration/migrate_5_0/java.asciidoc
+++ b/docs/reference/migration/migrate_5_0/java.asciidoc
@@ -22,6 +22,25 @@ can be replaced with
 client.prepareSearch(indices).setSource(new SearchSourceBuilder().size(0).query(query)).get();
 -----
 
+==== Suggest api has been removed
+
+The suggest api has been removed from the Java api, use the suggest option in search api, it has been optimized
+for suggest-only request.
+
+The following call
+
+[source,java]
+-----
+client.prepareSuggest(indices).addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s")).get();
+-----
+
+can be replaced with
+
+[source,java]
+-----
+client.prepareSearch(indices).suggest(new SuggestBuilder().addSuggestion("foo", SuggestBuilders.completionSuggestion("field").text("s"))).get();
+-----
+
 ==== Elasticsearch will no longer detect logging implementations
 
 Elasticsearch now logs only to log4j 1.2. Previously if log4j wasn't on the