Elastic Search Java API documentation lacking

Hi all, I'm running elasicsearch 1.5.2 embedded in my java app. I spent most of a day trying to add a custom dynamic mapping to my index via the CreateIndexRequestBuilder Java API to disable date detection.
I used the documentation here as my guide:
https://www.elastic.co/guide/en/elasticsearch/guide/master/custom-dynamic-mapping.html
I kept getting a "Root type mapping not empty after parsing" error any time I tried to add the mapping. Adding the mapping via the REST API always worked fine.
After a lot of forum searching (which didn't help) and fiddling around I discovered the "mappings" node in the example needed to be removed when using the Java API.
This is the JSON the guide says to use with the REST API:

{
"mappings": {
    "my_type": {
        "date_detection": false
    }
}

}

This is the JSON I had to use to get the Java API to work:

 {
    "my_type": {
        "date_detection": false
    }
}

I couldn't find documentation about that anywhere. If it exists, could someone point me in the right direction so I know for next time? I think it would be very helpful to have more examples of how to use the Java API along side the REST API, especially for calls that require you to supply a JSON document as input.

In general, the unit and integration tests are the best way to find how
the Java API is used. The Rest Action classes are another way, but more
generic.

Cheers,

Ivan