In my opinion, much of the described features of an API client actually do not belong in a client implementation. An API client cannot be shipped for all platforms. That either blocks platforms to use your API or leaves room for API consumers to get around your policies, like throttling and caching. I think enforcing policies should be done much closer to your API on the server side. An API proxy gateway could be used for most of the described points and would secure your API much better, without the extra effort of writing client libraries.
Your REST API should come with a client
51–60 of 82 posts
Re: Your REST API should come with a client
#52If 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?
Yeah good question.
I think GET would be a reasonable default here, perhaps 123 is a query string parameter.
For update / POST, create / PUT etc. it's less clear cut in my example language of Python since all we have is a callable, we don't have constructs such as "new" to map behaviours to (repurposing "del" isn't possible).
Perhaps there's an extra parameter:
client.account(id=123, name="something", _method=PUT)
client.account(id=123, name="something").PUT()
from rest import client, PUT
PUT(client.account(id=123, name="something"))
Re: Your REST API should come with a client
#53The Google APIs Client Generator is an awesome tool that automates this process. It takes a service description and generates a complete client library: https://code.google.com/p/google-apis-client-generator/ The service is defined in a platform-neutral discovery document, which can be used by any provider: https://developers.google.com/discovery/v1/reference/apis There are generators for Python, Java, .NET, Objectiv…
> The Google APIs Client Generator is an awesome tool that automates this process. It takes a service description and generates a complete client library So we've gone full circle and arrived back at SOAP. Why didn't we just keep using SOAP in the first place?
Because SOAP is an unnecessary overhead and complication. It also kills performance.
Re: Your REST API should come with a client
#54If 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
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.
Re: Your REST API should come with a client
#55Your API should handle collections in any case. Otherwise this is just reinventing ESB while losing most of the stability and service management benefits by fragmenting and decentralising.
Re: Your REST API should come with a client
#56Relatedly, 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…
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.
Re: Your REST API should come with a client
#57Wow! We did exactly these things in Q. I was surprised to see exactly the features we tout in our SDK mentioned one by one. Compare to this:
http://platform.qbix.com/guide/patterns
The Q platform was supposed to take care of the things that you have to do anyway when writing social apps.
Re: Your REST API should come with a client
#58If 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
http://platform.qbix.com/guide/patterns
Does this suck?
Re: Your REST API should come with a client
#59If 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
Agreed; REST clients/frameworks should have ways of handling all six of these problems--none of them are specific to a particular API.
If the client lib has an API-specific way of handling "caching", say, then the number of ways of handling "caching" is O(n) in the number of APIs you consume. If you use the REST APIs directly, then the HTTP's standard, debugged, documented caching mechanism is the only one you ever need to know.
Re: Your REST API should come with a client
#60If 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
A few things off the top of my head which are different across many RESTful APIs which prevent a unified client from being possible:
- Referring to other data paths in the API in a standard format
- Authentication. Shy of OAuth, it is totally different on each API. Most APIs avoid OAuth because its a PITA
- Partial PUTs vs PATCH vs sub-resources
All sorts of minor things are different across rest APIs, and that results in client libraries needing to be widely different.
We are in need of a standardized API format which we can build compatible server & client libraries against. Something like SOAP for the JSON era. There are a few out there, but none have really gone anywhere. Are any of these extended-REST wrappers in production by any big companies? I'd love to be corrected.
If not, maybe a high-profile company with a really nice API design could publish a standard on their API structure and refactor out their transport code to provide us with these libraries. If successful, they could be known for introducing a widely-used transport layer for the web industry.