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

41–50 of 82 posts

Re: Your REST API should come with a client

#41

Post by arethuza »

CraigJPerry wrote: post #21

If REST client libs didn't suck, this wouldn't be needed. It's a load of effort to correctly consume from a RESTful webservice currently. I should be able to get going in my REPL with something like: >>> from rest import client >>> proxy = client(url) >>> print proxy.resources ['foo', 'bar'] >>> help(client.foo) Help text from the rest service... >>> client.foo(123) 321 # repeat calls transparently handle caching

Maybe I'm being a bit dim, but could you explain what "client.foo(123)" does in this client - it appears to be a resource and 'callable' - so is this doing a GET on that resource, what about other methods?

Re: Your REST API should come with a client

#42

Post by skion »

Agree with this, even if just done in one reference language. It is much easier for the community to port an existing binding to other languages, than to implement a new client from scratch.

Two notes:

2) No need to mask requests with a HEAD; a GET can also return a 304 directly.

6) De-duplication of calls: Any method except POST should be idempotent already, hence also a retry-on-error is trivial in those cases.

Re: Your REST API should come with a client

#43

Post by tlrobinson »

Most of these things should be (optional) features of a good HTTP client library, which is kind of the point of following conventions like REST.

Maybe that just means writing a thin wrapper around one of these libraries specific for your API. But don't reinvent the wheel every time.

Re: Your REST API should come with a client

#44

Post by MichaelGG »

arethuza wrote: post #37
voltagex_ wrote: post #32

Earlier quoted context omitted.

https://pypi.python.org/pypi/wadllib/1.1.4 looks quite complicated. I'd really like to be able to do some_object.some_remote_method_call(parameters) like the parent. I guess REST is there to make it easier for other people to implement your API. SOAP was hard without libraries, I can hit your REST endpoint with curl.

"I can hit your REST endpoint with curl." I must admit that was my initial reaction when I saw the title of this article - I tend to regard curl as the universal RESTful API client. I don't think I've written or consumed a RESTful API where I didn't spend a fair amount of time interacting with the system through curl.

cURL works fine for RPC-style or non-RESTful clients too. Instead of "-XPUT" you make your URL end with /foo/addfoo or something. And who cares if the FooID is in the URL or in postdata? In fact, cURL makes it easier to add another data parameter than change the URL.

Re: Your REST API should come with a client

#45

Post by jalfresi »

Your docs should be curl examples showing how to use the Rest API. If you are providing a client library in multiple libraries, not only are you doing it wrong, but you've also missed the entire point of building a Rest API in the first place.

Your consumers should know how to handle HTTP requests from within their language. If they don't, then no Client for your API will save them.

Re: Your REST API should come with a client

#46

Post by cordite »

MichaelGG wrote: post #29
johns wrote: post #10

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…

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.

Re: Your REST API should come with a client

#47

Post by jbert »

> You’ll have to mask GET requests with a HEAD request and appropriately handle HTTP status code 304 for resource not modified.

I'm not sure I understand this. Surely the point of if-modified-since and etag headers is that you can send them in the GET request and get back a 304, there is no need to do a HEAD-then-GET?

Re: Your REST API should come with a client

#48

Post by CraigJPerry »

icebraining wrote: post #40
CraigJPerry wrote: post #21

If REST client libs didn't suck, this wouldn't be needed. It's a load of effort to correctly consume from a RESTful webservice currently. I should be able to get going in my REPL with something like: >>> from rest import client >>> proxy = client(url) >>> print proxy.resources ['foo', 'bar'] >>> help(client.foo) Help text from the rest service... >>> client.foo(123) 321 # repeat calls transparently handle caching

Have you tried Hammock? It fakes it very well: >>> from hammock import Hammock as Github >>> # Let's create the first chain of hammock using base api url >>> github = Github('https://api.github.com') >>> # Ok, let the magic happens, ask github for hammock watchers >>> resp = github.repos('kadirpekel', 'hammock').watchers.GET() >>> # now you're ready to take a rest for the rest the of code :) >>> for watcher in resp.j…

This is the closest i've seen. Excellent link, thanks!

Re: Your REST API should come with a client

#49

Post by nailer »

I think there's another benefit here: edge cases will show up. I wrote a Python client for a company's REST API which revealed an RFC bug during testing. From the source:

> For POSTs we do NOT encode our data, as CompanyX's REST API expects square brackets which are normally encoded according to RFC 1738. urllib.urlencode encodes square brackets which the API doesn't like.

Retrospectively, I should have asked the company to fix their bug, rather than work around it myself, but at the time I was a less confident programmer.

Post reply on HN