Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Your REST API should come with a client

silota.com

Post reply on HN
Print view View original

11–20 of 82 posts

Re: Your REST API should come with a client

#11

Post by patio11 »

thomasahle wrote: post #6

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?

They wouldn't be substantially identical clients.

For example, I have extensive use of Twilio and Pin Payments (among other APIs) in Appointment Reminder. My use of the Twilio API can potentially spike into the hundreds of requests a second range, but if it gets into thousands of requests a second, that needs to throw a PresidentOfMadagascarException ("Shut. Down. Everything.") Code which does not interact with the Twilio API but instead implements meta-features on top of the Twilio API comprises 80%+ of lines of code implicating the Twilio API in my application.

By comparison, querying the Pin Payments API doesn't need a rate limit at all, but does need a sane caching strategy, because it requires thousands of API calls to answer a simple, common question like "How much did we sell in 2013?" Again, meta-features for the API comprise over 80% of lines of code implicating that API, but they're totally different meta-features.

AR is doing the 90% case with both of these APIs -- sane defaults in first-party clients would have greatly eased my implementation of them, allowing me to focus on features which actually sell AR, to the benefit of both my business and those of the APIs at issue, since their monthly revenue from me scales linearly with my success.

Re: Your REST API should come with a client

#15

Post by madeofpalk »

gane5h wrote: post #5
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.

Also, Javascript https://dev.twitter.com/docs/twitter-ids-json-and-snowflake

Re: Your REST API should come with a client

#16

Post by pbreit »

I still feel like clients defeat the whole purpose of using simple technologies like HTTP verbs and JSON. But I can see that a) if your constituents want them you probably have to provide them and b) there might be some marketing benefit. Other than that, I think it's a shame.

And the reasons in the post are not particularly compelling. 1) Batch requests are usually unnecessary or benefit from a call optimized for batching. 2) Caching rarely needed, potentially dangerous and can be done elsewhere. 3) Throttling can/should be performed elsewhere and no way to prevent DOS anyway. 4) Timeouts are usually easy. 5) GZIP rarely necessary. 6) Dangerous to let someone else's code do it.

Re: Your REST API should come with a client

#17

Post by pbreit »

patio11 wrote: post #2

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.c…

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

Re: Your REST API should come with a client

#20

Post by patio11 »

pbreit wrote: post #17
patio11 wrote: post #2

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.c…

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

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

Post reply on HN