[[anatomy]]
== API Anatomy

Once a <<client,GClient>> has been
obtained, all of Elasticsearch APIs can be executed on it. Each Groovy
API is exposed using three different mechanisms.


[[closure]]
=== Closure Request

The first type is to simply provide the request as a Closure, which
automatically gets resolved into the respective request instance (for
the index API, its the `IndexRequest` class). The API returns a special
future, called `GActionFuture`. This is a groovier version of
Elasticsearch Java `ActionFuture` (in turn a nicer extension to Java own
`Future`) which allows to register listeners (closures) on it for
success and failures, as well as blocking for the response. For example:

[source,groovy]
--------------------------------------------------
def indexR = client.index {
    index "test"
    type "_doc"
    id "1"
    source {
        test = "value"
        complex {
            value1 = "value1"
            value2 = "value2"
        }
    }
}

println "Indexed $indexR.response.id into $indexR.response.index/$indexR.response.type"
--------------------------------------------------

In the above example, calling `indexR.response` will simply block for
the response. We can also block for the response for a specific timeout:

[source,groovy]
--------------------------------------------------
IndexResponse response = indexR.response "5s" // block for 5 seconds, same as:
response = indexR.response 5, TimeValue.SECONDS //
--------------------------------------------------

We can also register closures that will be called on success and on
failure:

[source,groovy]
--------------------------------------------------
indexR.success = {IndexResponse response ->
    println "Indexed $response.id into $response.index/$response.type"
}
indexR.failure = {Throwable t ->
    println "Failed to index: $t.message"
}
--------------------------------------------------


[[request]]
=== Request

This option allows to pass the actual instance of the request (instead
of a closure) as a parameter. The rest is similar to the closure as a
parameter option (the `GActionFuture` handling). For example:

[source,groovy]
--------------------------------------------------
def indexR = client.index (new IndexRequest(
        index: "test",
        type: "_doc",
        id: "1",
        source: {
            test = "value"
            complex {
                value1 = "value1"
                value2 = "value2"
            }
        }))

println "Indexed $indexR.response.id into $indexR.response.index/$indexR.response.type"
--------------------------------------------------


[[java-like]]
=== Java Like

The last option is to provide an actual instance of the API request, and
an `ActionListener` for the callback. This is exactly like the Java API
with the added `gexecute` which returns the `GActionFuture`:

[source,groovy]
--------------------------------------------------
def indexR = node.client.prepareIndex("test", "_doc", "1").setSource({
    test = "value"
    complex {
        value1 = "value1"
        value2 = "value2"
    }
}).gexecute()
--------------------------------------------------