[mikeknoop]

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.

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:

If you are deviating from the norm, you're doing it wrong.

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.

[jeremyjh]

Can you respond directly to some of the points raised in the article? For example, ensuring SSL certs are validated?

[mikeknoop]

Sure. I'll start with this: as far as client libraries go, Braintree is doing it right. Because it's the only thing they support, they are incentivized to make sure it is feature complete and bug free.

SSL: It is not the onus of the vendor to ensure people are properly securing requests. I have seen horrendous things done in the name of "security" but it only adds headaches. Fix this at the client level. SSL everywhere is sufficient. By extension, vendors often introduce mechanics because they want to make the world better: http://xkcd.com/927/

Platform Support: I think the counter-argument is community client libraries, which the OP is correct: they are worse. The stability + scaling + support issues mentioned by OP can usually be solved by better API design and better architecture behind the scene.

Backwards Compatibility: OP claims you never have to update your code if you use their client library. This is likely true. Good API design would dictate not breaking exposed endpoints unless there is new functionality to be had. In this case, to take advantage of any new API features, you'd still have to update your code. No cost savings are had either way.

[jeremyjh]

>SSL: It is not the onus of the vendor to ensure people are properly securing requests.

Two responses: first, Braintree customers may appreciate knowing that Braintree provides a safer implementation than whatever the (third)contractor that they hired to build thier web app might throw together.

Second, fraud does directly impact their business, regardless of the entry point used by the attacker. Even if they don't get stuck for the money directly, they are going to lose time talking to customers and helping with investigations.

They don't have to do either, but they may find that they can make some types of customer relationships profitable that would not be for a competing business that doesn't do as much hand-holding.

[hennk]

I can understand that a payment gateway takes security more serious, as it can directly affect their business if clients handle SSL wrongly.

Maybe a kind of chaos-monkey for API connections could help? Every now and then the API returns a wrong SSL certificate. If the client ignores this, they could notify the customer, or directly block further access until the problem is solved? :)

[alanctgardner2]

The big problem I see is that SSL requires an unbroken chain of trust all the way along. If I have client-side code connecting to my server, which is then connecting to a third party server, all of those links have to be secured. As someone else pointed out, it`s nice to make your payment processing secure, but at some point the developer also has to step up and ensure their half of the bargain is upheld. If I`m sending credit card details to my backend over HTTP for some reason, no API in the world will stop me.

Even looking at Stripe; they provide a JS library so you can do client-side encryption. However, if you include that JS library on an incorrectly SSLed page, a malicious party could replace it without you knowing. Even with extensive hand-holding, if a user is going to implement SSL badly, there will be security risks.

The only sure-fire solution is for the developers of SSL libraries to come together and implement sane default options, and clear documentation of how not to do things. Looking at the docs for OpenSSL, it`s impossible to easily discern what counts as a sane configuration. The same problem propagates itself into language-specific libraries, where the dev wasn`t quite sure what options to tick to begin with. And so it goes.

[debacle]

What about some sort of client library generator, similar to how .NET languages can generate code from other .NET WSDLs?

[edanm]

Is there a good book/resource on learning REST API ideas? I'm looking for a beginner's resource for someone who doesn't really grok the ideas behind REST and the motivation for REST. But also something that gets technical very quickly - I've been programming for long enough that I pick ideas up very quickly.

[sopooneo]

I'm sort of with you, though I've read quite a bit at this point and interacted with a number of APIs of varying degrees of "RESTfulness".

The biggest question I wish the various tutorials would address is: why is REST a good idea? Why is this particular way of doing things better than others?

And here's one thing I believe is true, that I have literally never seen in a REST tutorial: sometimes REST is not the best way to go. Sometimes an RPC architecture is better.

[BerislavLopac]

"sometimes REST is not the best way to go. Sometimes an RPC architecture is better."

I think that the full versions of there acronyms make a pretty good job of explaining what is best when.

"REpresentational State Transfer": obviously, it transfers state, i.e. information about a certain resource at a given moment. "Remote Procedure Call": obviously, it calls a procedure, which may involve several state changes and other activities. Of course, a procedure may be masked behind a REST endpoint (e.g. when you POST some data and do some procedure before you end up with a certain state) and vice versa (e.g. a simple getter), but you may pretty much view REST as the SQL of the Web, and RPC as stored procedures.

[SilasX]

>but you may pretty much view REST as the SQL of the Web, and RPC as stored procedures.

Indeed, but that just raises the question: what would possess you to write an app out of SQL calls rather than general functions? So then why do the Web equivalent thereof?

[BerislavLopac]

You don't, of course. What you do is build an app which is using REST to store data somewhere online, and the app itself may be in the user's browser, on a mobile phone or anywhere else for that matter.

[SilasX]

Definitely. Just pass that memo along to the "apps should work purely through REST API calls" crowd.

[sigsergv]

I'd recommend this book http://www.amazon.com/RESTful-Web-Services-Cookbook-Scalabil...

It's amazing, really. It's not just a recipies list, it explains a lot of very important REST cases, and also when to use or not to use REST.

[michaelfairley]

Not your typical book, but it's very good: http://designinghypermediaapis.com/

[edanm]

Interesting. I wasn't sure about buying it, but ended up purchasing. Only after realizing that it was by Steve Klabnik, a name I recognize, probably from HN. I wonder why there isn't more info on the front page, even a sample/TOC would be nice.

I'll be going through it tomorrow, if I remember I'll come back to post a mini review.

[toomuchtodo]

This. After seeing the URL posted above, I clicked the link just to see if it was Steve's book. Disappointed he doesn't put his name prominently on the landing page.