# REST Suggester API

The REST Suggester API binds the 'Suggest API' to the REST Layer directly. Hence there is no need to touch the query layer for requesting suggestions.
This API extracts the Phrase Suggester API and makes 'suggestion request' top-level objects in suggestion requests. The complete API can be found in the
underlying ["Suggest Feature API"](http://www.elasticsearch.org/guide/reference/api/search/suggest.html).

# API Example
The following examples show how Suggest Actions work on the REST layer. According to this a simple request and its response will be shown.

## Suggestion Request
```json
curl -s -XPOST 'localhost:9200/_suggest -d {
    "text" : "Xor the Got-Jewel",
    "simple_phrase" : {
        "phrase" : {
            "analyzer" : "bigram",
            "field" : "bigram",
            "size" : 1,
            "real_word_error_likelihood" : 0.95,
            "max_errors" : 0.5,
            "gram_size" : 2
        }
    }
}
```
This example shows how to query a suggestion for the global text 'Xor the Got-Jewel'. A 'simple phrase' suggestion is requested and
a 'direct generator' is configured to generate the candidates.

## Suggestion Response
On success the request above will reply with a response like the following:
```json
{
    "simple_phrase" : [ {
        "text" : "Xor the Got-Jewel",
        "offset" : 0,
        "length" : 17,
        "options" : [ {
            "text" : "xorr the the got got jewel",
            "score" : 3.5283546E-4
        } ]
    } ]
}
```
The 'suggest'-response contains a single 'simple phrase' which contains an 'option' in turn. This option represents a suggestion of the
queried text. It contains the corrected text and a score indicating the probability of this option to be meant.

Closes elastic#2774

src/main/java/org/elasticsearch/action/ActionModule.java

@@ -112,6 +112,8 @@
 import org.elasticsearch.action.percolate.TransportPercolateAction;
 import org.elasticsearch.action.search.*;
 import org.elasticsearch.action.search.type.*;
+import org.elasticsearch.action.suggest.SuggestAction;
+import org.elasticsearch.action.suggest.TransportSuggestAction;
 import org.elasticsearch.action.support.TransportAction;
 import org.elasticsearch.action.update.TransportUpdateAction;
 import org.elasticsearch.action.update.UpdateAction;
@@ -205,6 +207,7 @@ protected void configure() {
         registerAction(DeleteAction.INSTANCE, TransportDeleteAction.class,
                 TransportIndexDeleteAction.class, TransportShardDeleteAction.class);
         registerAction(CountAction.INSTANCE, TransportCountAction.class);
+        registerAction(SuggestAction.INSTANCE, TransportSuggestAction.class);
         registerAction(UpdateAction.INSTANCE, TransportUpdateAction.class);
         registerAction(MultiGetAction.INSTANCE, TransportMultiGetAction.class,
                 TransportShardMultiGetAction.class);

src/main/java/org/elasticsearch/action/suggest/ShardSuggestRequest.java

@@ -0,0 +1,61 @@
+/*
+ * Licensed to ElasticSearch and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. ElasticSearch licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.action.suggest;
+
+import java.io.IOException;
+
+import org.elasticsearch.action.support.broadcast.BroadcastShardOperationRequest;
+import org.elasticsearch.common.Nullable;
+import org.elasticsearch.common.bytes.BytesReference;
+import org.elasticsearch.common.io.stream.StreamInput;
+import org.elasticsearch.common.io.stream.StreamOutput;
+
+/**
+ * Internal suggest request executed directly against a specific index shard.
+ */
+class ShardSuggestRequest extends BroadcastShardOperationRequest {
+
+    private BytesReference suggestSource;
+
+
+    ShardSuggestRequest() {
+    }
+
+    public ShardSuggestRequest(String index, int shardId, @Nullable String[] filteringAliases, SuggestRequest request) {
+        super(index, shardId, request);
+        this.suggestSource = request.suggest();
+    }
+
+    public BytesReference suggest() {
+        return suggestSource;
+    }
+
+    @Override
+    public void readFrom(StreamInput in) throws IOException {
+        super.readFrom(in);
+        suggestSource = in.readBytesReference();
+    }
+
+    @Override
+    public void writeTo(StreamOutput out) throws IOException {
+        super.writeTo(out);
+        out.writeBytesReference(suggestSource);
+    }
+}

src/main/java/org/elasticsearch/action/suggest/ShardSuggestResponse.java

@@ -0,0 +1,60 @@
+/*
+ * Licensed to ElasticSearch and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. ElasticSearch licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.action.suggest;
+
+import org.elasticsearch.action.support.broadcast.BroadcastShardOperationResponse;
+import org.elasticsearch.common.io.stream.StreamInput;
+import org.elasticsearch.common.io.stream.StreamOutput;
+import org.elasticsearch.search.suggest.Suggest;
+
+import java.io.IOException;
+
+/**
+ * Internal suggest response of a shard suggest request executed directly against a specific shard.
+ */
+class ShardSuggestResponse extends BroadcastShardOperationResponse {
+
+    private final Suggest suggest;
+
+    ShardSuggestResponse() {
+        this.suggest = new Suggest();
+    }
+
+    public ShardSuggestResponse(String index, int shardId, Suggest suggest) {
+        super(index, shardId);
+        this.suggest = suggest;
+    }
+
+    public Suggest getSuggest() {
+        return this.suggest;
+    }
+
+    @Override
+    public void readFrom(StreamInput in) throws IOException {
+        super.readFrom(in);
+        suggest.readFrom(in);
+    }
+
+    @Override
+    public void writeTo(StreamOutput out) throws IOException {
+        super.writeTo(out);
+        suggest.writeTo(out);
+    }
+}

src/main/java/org/elasticsearch/action/suggest/SuggestAction.java

@@ -0,0 +1,46 @@
+/*
+ * Licensed to ElasticSearch and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. ElasticSearch licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.action.suggest;
+
+import org.elasticsearch.action.Action;
+import org.elasticsearch.client.Client;
+import org.elasticsearch.search.suggest.Suggest;
+
+/**
+ */
+public class SuggestAction extends Action<SuggestRequest, SuggestResponse, SuggestRequestBuilder> {
+
+    public static final SuggestAction INSTANCE = new SuggestAction();
+    public static final String NAME = "suggest";
+
+    private SuggestAction() {
+        super(NAME);
+    }
+
+    @Override
+    public SuggestResponse newResponse() {
+        return new SuggestResponse(new Suggest());
+    }
+
+    @Override
+    public SuggestRequestBuilder newRequestBuilder(Client client) {
+        return new SuggestRequestBuilder(client);
+    }
+}

src/main/java/org/elasticsearch/action/suggest/SuggestRequest.java

@@ -0,0 +1,177 @@
+/*
+ * Licensed to ElasticSearch and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. ElasticSearch licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.action.suggest;
+
+import java.io.IOException;
+import java.util.Arrays;
+
+import org.elasticsearch.action.ActionRequestValidationException;
+import org.elasticsearch.action.support.broadcast.BroadcastOperationRequest;
+import org.elasticsearch.client.Requests;
+import org.elasticsearch.common.Nullable;
+import org.elasticsearch.common.Strings;
+import org.elasticsearch.common.bytes.BytesArray;
+import org.elasticsearch.common.bytes.BytesReference;
+import org.elasticsearch.common.io.stream.StreamInput;
+import org.elasticsearch.common.io.stream.StreamOutput;
+import org.elasticsearch.common.xcontent.XContentHelper;
+import org.elasticsearch.common.xcontent.XContentType;
+
+/**
+ * A request to get suggestions for corrections of phrases. Best created with
+ * {@link org.elasticsearch.client.Requests#suggestRequest(String...)}.
+ * <p/>
+ * <p>The request requires the query source to be set either using {@link #query(org.elasticsearch.index.query.QueryBuilder)},
+ * or {@link #query(byte[])}.
+ *
+ * @see SuggestResponse
+ * @see org.elasticsearch.client.Client#suggest(SuggestRequest)
+ * @see org.elasticsearch.client.Requests#suggestRequest(String...)
+ */
+public class SuggestRequest extends BroadcastOperationRequest<SuggestRequest> {
+
+    static final XContentType contentType = Requests.CONTENT_TYPE;
+
+    @Nullable
+    protected String routing;
+
+    @Nullable
+    private String preference;
+
+    private BytesReference suggestSource;
+    private boolean suggestSourceUnsafe;
+
+    SuggestRequest() {
+    }
+
+    /**
+     * Constructs a new suggest request against the provided indices. No indices provided means it will
+     * run against all indices.
+     */
+    public SuggestRequest(String... indices) {
+        super(indices);
+    }
+
+    @Override
+    public ActionRequestValidationException validate() {
+        ActionRequestValidationException validationException = super.validate();
+        return validationException;
+    }
+
+    @Override
+    protected void beforeStart() {
+        if (suggestSourceUnsafe) {
+            suggestSource = suggestSource.copyBytesArray();
+            suggestSourceUnsafe = false;
+        }
+    }
+
+    /**
+     * The Phrase to get correction suggestions for 
+     */
+    BytesReference suggest() {
+        return suggestSource;
+    }
+
+    /**
+     * set a new source for the suggest query  
+     */
+    public BytesReference suggest(BytesReference suggestSource) {
+        this.suggestSource = suggestSource;
+        this.suggestSourceUnsafe = false;
+        return suggestSource;
+    }
+
+    /**
+     * A comma separated list of routing values to control the shards the search will be executed on.
+     */
+    public String routing() {
+        return this.routing;
+    }
+
+    /**
+     * A comma separated list of routing values to control the shards the search will be executed on.
+     */
+    public SuggestRequest routing(String routing) {
+        this.routing = routing;
+        return this;
+    }
+
+    /**
+     * The routing values to control the shards that the search will be executed on.
+     */
+    public SuggestRequest routing(String... routings) {
+        this.routing = Strings.arrayToCommaDelimitedString(routings);
+        return this;
+    }
+
+    public SuggestRequest preference(String preference) {
+        this.preference = preference;
+        return this;
+    }
+
+    public String preference() {
+        return this.preference;
+    }
+
+    @Override
+    public void readFrom(StreamInput in) throws IOException {
+        super.readFrom(in);
+
+        routing = in.readOptionalString();
+        preference = in.readOptionalString();
+        suggestSource = in.readBytesReference();
+
+        suggestSourceUnsafe = false;
+    }
+
+    @Override
+    public void writeTo(StreamOutput out) throws IOException {
+        super.writeTo(out);
+
+        out.writeOptionalString(routing);
+        out.writeOptionalString(preference);
+        out.writeBytesReference(suggestSource);
+    }
+
+    @Override
+    public String toString() {
+        String sSource = "_na_";
+        try {
+            sSource = XContentHelper.convertToJson(suggestSource, false);
+        } catch (Exception e) {
+            // ignore
+        }
+        return "[" + Arrays.toString(indices) + "]" + ", suggestSource[" + sSource + "]";
+    }
+
+    public SuggestRequest suggest(BytesReference suggestSource, boolean contentUnsafe) {
+        this.suggestSource = suggestSource;
+        this.suggestSourceUnsafe = contentUnsafe;
+        return this;
+    }
+
+    public SuggestRequest suggest(String source) {
+        this.suggestSource = new BytesArray(source);
+        this.suggestSourceUnsafe = false;
+        return this;
+    }
+
+}