[bguthrie]

Note that this isn't a critique of the REST architectural style; rather, it documents their decision to prefer supplying clients with prebuilt libraries rather than a public API that their respective language communities can use to build their own. You could read the source to any one of their client libs and infer the rough structure of their services, so it's not all that private; they're simply choosing to leave what's there undocumented. It's an interesting approach, but not without its drawbacks.

[caseysoftware]

At Twilio, our REST API is fully documented but we still encourage people to use our helper libraries as much as possible.

It's not because we'd like to document the API less, but because there are related things - http connections, auth, etc - that need to be handled and it's easier to have the library do them. Further, the library serves to wrap the API in the idioms appropriate for the language. This may include data structures, but also includes things like variable names.

That way you can focus on your app in your chosen.. and only dig into the abstraction if you choose to.

[MatthewPhillips]

I have no knowledge of what BrainTree does, but if I'm picking a service with an API, I'm picking the one that is easiest to learn (preferably there is little that needs to be learned), I'm not picking one that requires me to switch languages -- or just as bad, locks me into one of a few languages I'm currently using.

[elarkin]

BrainTree does payments. They have concerns about security that most apps do not. Who really cares if bugged timeout/retry logic makes your app post twice to facebook? Probably no one. Who cares if bugged timeout/retry logic makes your app bill them twice? Probably everyone.

BrainTree and you may not make the same decision, and you both could be right.