When REST isn't Good Enough

We (Zapier) are in a particularly good place to comment on this. We have implemented about 70 very diverse web APIs in-house. Early on, we used client libraries because they were easy and convenient. That decision bit us, hard. (Most) client libraries are un-maintained, opaque, and difficult to extend.<p>We spent many months ripping every client library out down to the raw requests. We are in a unique position because of how many APIs we have to support, but the overarching advise we give to people designing APIs:<p>If you are deviating from the norm, you're doing it wrong.<p>REST APIs are nice because you can infer how to communicate with the API out of the gate. APIs are a pain and you only introduce headaches by not doing things in a sane, conventional fashion.

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.

Braintree isn't the only HTTPS API a developer will consume. Rather than bury the knowledge of HTTPS best practice in the black box of a library, why not exemplify it in language-specific examples of plain-old REST API documentation?<p>If the boilerplate for manually getting an SSL connection right in a given language is <i>that</i> obtuse, the "just use our library" pitch is even more compelling.<p>All this said, I have used Braintree's libraries and they are extremely well executed.<p>Not exposing REST API documentation externally (it surely exists <i>internally</i>, right?) just feels like a cop out.<p>(An argument I'm surprised was left out: it's easier for support staff to work with customers integrating with a good library than some home rolled REST client. I can imagine this to be true, but maybe a case of premature optimization if the majority of big API players expose and document their REST APIs anyway?)

I don't like REST. Making a call to a server should be like calling a function anywhere else - you have your parameters and return value. In REST the parameters are spread over 3 places, the action, the url and the post parameters themselves. It's a much better design to combine all your parameters in one place and keep things simple, for example -<p>REST version: UPDATE /course/324234 { description: "This is a level 1 course" }<p>Improved version: POST /course/UpdateDescription { courseId: 324234, description: "This is a level 2 course" }<p>In this case POST is always used for api calls. Course is the namespace, UpdateDesciption is the method name, and parameters are kept all together as JSON.

Braintree have made an interesting choice in keeping their REST API private and requiring customers use their client libraries. I think they could both have client libraries that they promote as well as a public REST API. Breaking down their reasons:<p>Security - agree with them on this, the more they can help their users make their systems secure the better. Not sure if it should preclude a public REST API but certainly motivates for having a good client library.<p>Platform Support - another good reason to have the client library, essentially encoding best practice in the client. I've certainly seen customers abuse features of our APIs. Again, not sure if it should mean keeping the REST API private. Certainly it's a good idea to be defensive on both the client and server (e.g. for queries that request too much data, rate limiting etc.).<p>Backwards compatibility - Here I disagree with Braintree. I think it should be just as easy to manage backwards compatibility purely on the server side.

This has been my approach to internal service design as well. It's far easier to make sure people integrate properly by providing a rich, well-documented API client library than it is to rely solely on the REST-based one. REST APIs are hard to document, and require a lot of orthogonal boilerplate to even make the requests properly.<p>Making a client library is also a great way to "dogfood" your REST API - you know a developer will write code, not HTTP calls, to interact with your service. The client API allows you to test out that code and make sure your API is well designed.

Why not provide a C api? This would make it easy for community language bindings to capture the benefits you describe in languages you aren't natively supporting (such as Go, Erlang or Haskell).

It's a shame there isn't some simple standard (de-facto or otherwise) way of documenting REST APIs such that an idiomatic client library for each language could be generated automatically.<p>The OPTIONS method is a really underused part of HTTP and would be great for this purpose: <a href="http://zacstewart.com/2012/04/14/http-options-method.html" rel="nofollow">http://zacstewart.com/2012/04/14/http-options-method.html</a>

There are several good points in the article. Particular the one about https.<p>That said as a clojure dev I'd much rather work with a nice clojure http library like clj-http than have to use their provided java library.

The platform support argument is not very persuasive here. The beauty of open source and the community is that when you combine a popular service with common platforms that are likely to be used, it is likely someone in the community will release the needed api. Why not provide some community support for the platforms, but allow the users to release an api where they know their needs better than you do?<p>On the other hand, the security argument is quite strong. Improperly implemented SSL handshaking, especially when dealing with payment transactions like they do, has the potential to be devastating. But this is where interacting with the community that is making the api's would be key. There's a lot of value to be had when company and community development work together. They could contribute the ssl code themselves to the open source client projects.

I don't really care for this. The promise of web technologies, which has finally become reality over he past few hears, is obviating the need for client libraries. This benefits. Oth providers and consumers alike. The benefits cited by the OP are not that compelling. Most (all?) other APIs allow/encourage direct access so for a large number of developers, that's a strong preference.

The title should add "by itself" at the end, as they are still using REST - just adding client libraries.

This headline is atrocious, this article has so incredibly little to do with REST mechanics.