Your REST API should come with a client

#1

Post by gane5h » Mon, Apr 28, 2014, 4:40 AM UTC

Your REST API should come with a client
silota.com

Re: Your REST API should come with a client

#2

Post by patio11 » Mon, Apr 28, 2014, 5:47 AM UTC

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.)

Re: Your REST API should come with a client

#3

Post by AYBABTME » Mon, Apr 28, 2014, 5:56 AM UTC

Another reasons is that your API likely sucks/is broken if you haven't made a client for it (and thus figured out the gaps/problems).

Re: Your REST API should come with a client

#4

Post by krob » Mon, Apr 28, 2014, 6:03 AM UTC

It's nice that this article claims everyone who makes an api should provide a client. But what happens when it uses hypermedia restful constraints? I think that any company which is able to provide multiple implementations for their API has already made it financially to afford those luxuries.

I know of some large companies which do this already, one of them being braintree, which offers an amazing API in many different languages, but they are already profitable and were bought by paypal.

Re: Your REST API should come with a client

#5

Post by gane5h » Mon, Apr 28, 2014, 6:05 AM UTC

AYBABTME wrote: post #3

Another reasons is that your API likely sucks/is broken if you haven't made a client for it (and thus figured out the gaps/problems).

I learnt this the hard way. Initially, I designed the API with bigints for ids and found some older versions of PHP didn't support bigints. I had to switch to using strings.

Re: Your REST API should come with a client

#6

Post by thomasahle » Mon, Apr 28, 2014, 6:19 AM UTC

    Caching, throttling, timeouts, gzip, error handling.

This all seems like something any serious user of a REST API should know how to handle very well. If not otherwise, then by use of a standard library.

Why does every API owner have to write basically identical clients in every language out there?

Re: Your REST API should come with a client

#7

Post by fosk » Mon, Apr 28, 2014, 6:25 AM UTC

krob wrote: post #4

It's nice that this article claims everyone who makes an api should provide a client. But what happens when it uses hypermedia restful constraints? I think that any company which is able to provide multiple implementations for their API has already made it financially to afford those luxuries. I know of some large companies which do this already, one of them being braintree, which offers an amazing API in many differ…

I'm biased, since I'm the founder of Mashape [1], but maybe this could be of some interest. I'd like to point out that one of the features that Mashape offers is auto-generating client libraries in 8 different languages, leveraging Unirest [2] that we open sourced last year.

[1] http://mashape.com

[2] http://unirest.io

Re: Your REST API should come with a client

#8

Post by ejain » Mon, Apr 28, 2014, 6:28 AM UTC

Fine, but you can't provide clients for all languages and frameworks, so make sure your REST API is simple enough for those who need to make do without an official client library.

Re: Your REST API should come with a client

#9

Post by ejain » Mon, Apr 28, 2014, 6:29 AM UTC

AYBABTME wrote: post #3

Another reasons is that your API likely sucks/is broken if you haven't made a client for it (and thus figured out the gaps/problems).

Your integration tests should count as one client?

Re: Your REST API should come with a client

#10

Post by johns » Mon, Apr 28, 2014, 6:29 AM UTC

Providers should definitely provide clients. This is one of the things I worked on at Twilio and it's extremely important for onboarding new customers. Support as many languages and frameworks as you can sustain and make them first-class (just as well documented as REST, native to the language, etc).

However, I've also seen the other side of this working at IFTTT where (at the time) we had a gemfile a mile long. That got really hairy. I now try to avoid using clients. I go into it in great detail here: https://www.youtube.com/watch?v=dBO62A3XaSs and we've talked about this many times on trafficandweather.io if you want to learn more.