Not only should you include a client, you should write the client first.
Your REST API should come with a client
71–80 of 82 posts
Re: Your REST API should come with a client
#72Providers 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…
I just watched the talk. It's really interesting and raises a few things I haven't thought about before. Do you have any more information about automatic service/endpoint discovery and also about the smart HTTP client you use? I would have thought that failing over to another endpoint address would have been done at a load balancer level.
I can't recall the exact episode, but we talked more about smart client on trafficandweather.io
We definitely need to publish more about it
Re: Your REST API should come with a client
#73I 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 ba…
"5) GZIP rarely necessary." if the server already has the bytes gzipped, it is often pure win to ship the gzipped bytes: consider that the client may be able to finish uncompressing the gzipped response earlier than it could otherwise have received the last byte of the uncompressed response.
That's a neat idea. But in the case that the server doesn't have them zipped, I'm not sure that the blanket statement made in the blog post is really right, either.
Re: Your REST API should come with a client
#74Earlier quoted context omitted.
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…
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.
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
Re: Your REST API should come with a client
#75Earlier quoted context omitted.
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.
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
You live in cuckoo land if you think ruby/python are more widely used than Java/C#.
Re: Your REST API should come with a client
#76Earlier quoted context omitted.
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
You live in cuckoo land if you think ruby/python are more widely used than Java/C#.
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
Re: Your REST API should come with a client
#77Earlier quoted context omitted.
This kind of thing is why I'm predicting a return to WS-*, or else a reimplementation of it on top of REST. The XML backlash was mostly correct but having a standard, well-specified way of creating HTTP APIs and generating clients for them from a single endpoint is a baby we threw out with the bathwater.
The horribly-named HATEOAS is one possible solution: http://timelessrepo.com/haters-gonna-hateoas
Yes, if HATEOAS were actually done, all you'd need to do is have libraries for handling the content types used in the API, and with a suitable generic client library everything else would come for free.
But virtually no one does that with their APIs, and virtually no one builds client libraries on the assumption that services will do that, so there's something of a chicken-and-egg problem.
Re: Your REST API should come with a client
#78Earlier quoted context omitted.
Is Twilio really rest? Versioning and formatting info in URLs isn't REST-like. Plus the docs suggest you construct URLs, which isn't RESTful. I love Twilio's API, I just don't understand the REST part. I fail to see how "PATCH /accounts/123/ " is better than "POST /accounts/updateaccount ", especially when hidden behind a lovely client.
It seems they try to provide a somewhat hypermedia oriented API. What I really don't like is they don't accept my accept headers, and I have to change the extension on the end. Going to /.json feels like ilk to me.
For some additional insight on accept based conneg. The guys who created it, really wish they hadn't.
http://www.alvestrand.no/pipermail/ietf-types/2006-April/001...
"Regarding proactive negotiation in HTTP/2, I'll note that Waka strips all negotiation fields. I find the entire feature revolting, from every architectural perspective, and would take the opportunity of 2.x to remove it entirely." Roy Fielding http://lists.w3.org/Archives/Public/ietf-http-wg/2013JanMar/...
Re: Your REST API should come with a client
#79[deleted]
Re: Your REST API should come with a client
#80Providers 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…
At Leftronic we've also started to avoid clients. When you connect to many APIs you start running into issues with poorly supported clients and mile-long pip freezes. We like providing our own clients to our API because it's a nice quick way to get started but I think nothing beats good old python-requests and reading API docs.