1) it is not covered by the latency SLA. This is buried pretty deep...
2) suddenly you get magical responses that are supposed to trigger the client to do something (e.g. sql qyeries with order by requires some algorithm client side). These things are not docoumented anywhere, you have to read the Node or Python client libs..
Using Cosmos mainly requires being on .NET and using the official driver that communicates over a closed undocumented binary protocol. (even the Java driver having the full SLAs and using the binary protocol was launched just weeks ago).
IMO it would have been less misleading if MS had just removed the docs for their REST API. Or at least put up a big warning about it being an undocumented afterthought.
Cosmos DB offers REST API to work with data, documented at . The primary focus of the REST API is SDK developers for platforms where we do not provide drivers yet. Just like most databases, we recommend to use provided drivers where available. This REST API is not intended for broad consumption by the apps. Your point about being more explicit about scenario the REST API is intended for and supported for is well taken. We will improve the documentation.
thanks for feedback!