5 ms·

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

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.

debacle 14y ago
What about some sort of client library generator, similar to how .NET languages can generate code from other .NET WSDLs?
jeremyjh 14y ago
Can you respond directly to some of the points raised in the article? For example, ensuring SSL certs are validated?
- mikeknoop 14y ago
  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/ 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 14y ago
    >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 14y ago
    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 14y ago
  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.
edanm 14y ago
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.
- michaelfairley 14y ago
  Not your typical book, but it's very good: http://designinghypermediaapis.com/ http://designinghypermediaapis.com/
  - edanm 14y ago
    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 14y ago
      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.
- sopooneo 14y ago
  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 14y ago

debacle 14y ago

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

jeremyjh 14y ago

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

mikeknoop 14y ago
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/ 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 14y ago
  >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 14y ago
  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 14y ago
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.

edanm 14y ago

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.

michaelfairley 14y ago
Not your typical book, but it's very good: http://designinghypermediaapis.com/ http://designinghypermediaapis.com/
- edanm 14y ago
  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 14y ago
    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.
sopooneo 14y ago
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 14y ago