Earlier quoted context omitted.
Sounds like the good ol days of SOAP and WSDL
No, please. No SOAP or WSDL. over engineered.
I just used SOAP on a architecture prototype earlier this year. It is pretty much alive in the classic enterprise world.
Your REST API should come with a client
61–70 of 82 posts
Re: Your REST API should come with a client
#62Re: Your REST API should come with a client
#63I think shipping your own client lib sort of defeats the whole point of REST as the "one true way" to build API's. I agree that building a client library is useful and makes it easier to integrate with, but it also proves that REST on its own is not completely superior than something as conceptually simple as JSON-RPC.
I fully understand the benefits of REST, but on a lot of projects, a single endpoint and a simple RPC protocol would be easier to integrate without need for a separate client library.
Also, client libraries don't always do the best job of making it clear when you are making api calls over the wire and that can be quite problematic.
For example, I've worked with code where it made an http request to get a price, which was then used in a Model calculation. This code looked completely harmless at the highest level, but each page request was hitting the server 100+ times to do all the calculations needed.
After finding the problem adding some caching was easy and now things run faster. However, having that level of abstraction and indirection makes it far less obvious if/when/where HTTP requests happen and that isn't always a good thing.
Re: Your REST API should come with a client
#64I 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…
I don't think the idea in the post was to perform throttling in the client. The idea is to provide a best practice handling of throttling in the client (e.g. what to do when receiving a 429). Since the 429 is mentioned in the article, it's a reasonable assumption that the throttling happens outside of the client.
Re: Your REST API should come with a client
#65I think https://github.com/pksunkara/alpaca is a good starting point. Given a web API, it generates client libraries in ruby, python, php and node.js
Are there any other alternatives to alpaca? How is the quality of the generate client code?
No, as far as I know, alpaca is the first of its type. As the author of the code, I can guarantee good quality of the generated client code. I have written the templates such that they follow their respective language conventions and ecosystems.
Re: Your REST API should come with a client
#66The 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 everybody's SOAP implementation is subtly different, leading to bugs/pain/things not working.
Re: Your REST API should come with a client
#67If 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 resul…
Authentication shenanigans and needing to use PATCH in a sane way are much better reasons for using a custom client than all six reasons listed in the original article...
I don't get what you mean about data paths, though. Even if you had a hypothetical good REST client you'd still want a single point to do the URL string assembly to save typing and do some validation but this doesn't really require a whole different client.
Re: Your REST API should come with a client
#68Earlier quoted context omitted.
Your integration tests should count as one client?
Your integration test will be more realistic and simpler to write if you use a client.
But if you do that, you're testing your client rather than your API. That's bound to matter: either your client is abstracting behavior and using only a specific subset of how your API could be used, or your client is not really useful.
For example, if your client implements fallback handling and caching behavior "the right way" for your API, and you only test using your client, then you're not testing your API when it is used "the wrong way" by developers who bypass your client. Those are important test cases too, unless you treat the wire protocol as an internal implementation detail and use your client's API as "the API". But if you do that, don't call it RESTful. (Technically it might still be RESTful, but that's a loaded term now and it will confuse developers who expect raw HTTP.)
Re: Your REST API should come with a client
#69If 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.
The horribly-named HATEOAS is one possible solution: http://timelessrepo.com/haters-gonna-hateoas
Re: Your REST API should come with a client
#70Earlier 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
Maybe, if the library support is there. Right now HATEOAS seems to mean replacing your domain-specific action tags with boilerplatey and not a lot else.