[patio11]

Relatedly, you'll want to ship first-party or "blessed" libraries for the big programming stacks as quickly as feasible. Start with the one your team uses and then roll out to the ones which are big with in your customers' industries. They're vastly easier to consume for many of your users than a standard REST API is. (Compare: Twilio::Sms.send(from, to, "This is a message.") with Httparty.post("https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Mess..., {:From => from, :To => to, :Message => "This is a message"}). Of course, in an actual application, after the third time writing that I'd start working on a buggy poorly tested wrapper for half of the Twilio API, or use someone's OSS buggy poorly tested wrapper for half of the Twilio API. I actually did this prior to Twilio releasing a first-party Ruby API and will be crying tears about that timing for years to come.)

[thejosh]

Funnily enough Mailgun[0] has started to feature codesnippets for CURL/Ruby/Python/PHP/Java/C# on their homepage for sending mail.

[0] http://www.mailgun.com/

[mattmanser]

Gah, I have mixed feeling about this.

When you're using their internal language it's often great. Any other and it's often a nightmare. For example, it's very common to see people write a bloody awful .Net wrapper that are completely non-idiomatic and a complete pita to use.

Often they're written in a way the author clearly doesn't understand OO or hasn't kept up with C# and still thinks it's just like Java so writes extremely old fashioned code. And namespaces. They want you use a million namespaces. It's a minor thing, but a completely unnecessary complication. They could stick everything in one namespace and get no conflicts.

And then, because they've put out client libraries, they don't document their API properly.

Google, as usual, are the worst offender, their .Net library is really bad and incredibly overcomplicated. It does make you wonder about all the hype of 'best' engineers.

The other problem is that they think you'll be using their API one way, when it needs to be another and their code just gets in the way, but because they don't have a snippet without using their library, you end up having to ILSpy their library and then get greeted with shockingly bad code with millions of pointless interfaces that only get used once, because, again, they don't understand .Net.

[jessaustin]

Google, as usual, are the worst offender, their .Net library is really bad and incredibly overcomplicated. It does make you wonder about all the hype of 'best' engineers.

Maybe their "'best' engineers" are working on anything but .Net? My impression of the Google culture is that they're more focused on platforms for which .Net is not a factor.

[conductr]

Tend to agree. Many individuals could write the libraries for ruby, python, JavaScript, and PHP. And it's likely that would cover 3/4 of your users needs. .net java and even some of the functional langs don't usually justify the dev time and experience gap.

* elaborate - small teams don't always have the experience or desire to support these langs. better left to the community

[mattmanser]

You live in cuckoo land if you think ruby/python are more widely used than Java/C#.

[conductr]

in the context of restful apis?

seems like it's mostly web apps that are building rest apis. Most web apps are ruby/python/php. I'm pretty sure, but could be wrong. My hypothesis is based on the builder of the web app uses langs they are familiar with when they build out a selection of client library. The claim of a lack of .Net libraries seems to justify my thinking

[pbreit]

You're typically going to copy/past a snippet either way. Doesn't seem like a huge win.

[patio11]

Maybe that was a poor example, since I picked something which is one line either way.

How about this message signature:

Twilio::PhoneNumbers.buy_a_number!(options) #returns the new number or raises an error

I have this implemented in the bowels of Appointment Reminder, because back in the day Twilio did not ship that functionality with the API. The "snippet" to do it requires about 30 lines. They're also probably the wrong 30 lines, because e.g. if Internet gremlins bushwhack one of the HTTP requests, it dies uncleanly. I'd have been mighty obliged if it was one line which worked atomically. (It is, to my understanding, now that there exists a decent first-party Twilio library. I recall showing that method on a slide at Twilio HQ one day while begging for that first party library to get created.)