Your REST API should come with a client

Relatedly, you&#x27;ll want to ship first-party or &quot;blessed&quot; 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&#x27; industries. They&#x27;re vastly easier to consume for many of your users than a standard REST API is. (Compare: Twilio::Sms.send(from, to, &quot;This is a message.&quot;) with Httparty.post(&quot;<a href="https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages/&quot;" rel="nofollow">https:&#x2F;&#x2F;api.twilio.com&#x2F;2010-04-01&#x2F;Accounts&#x2F;{AccountSid}&#x2F;Mess...</a>, {:From =&gt; from, :To =&gt; to, :Message =&gt; &quot;This is a message&quot;}). Of course, in an actual application, after the third time writing that I&#x27;d start working on a buggy poorly tested wrapper for half of the Twilio API, or use someone&#x27;s OSS buggy poorly tested wrapper for half of the Twilio API. I actually did this prior to Twilio releasing a first-party Ruby API and will be crying tears about that timing for years to come.)

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&#x27;s a shame.<p>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&#x2F;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&#x27;s code do it.

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

Providers should definitely provide clients. This is one of the things I worked on at Twilio and it&#x27;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).<p>However, I&#x27;ve also seen the other side of this working at IFTTT where (at the time) we had a gemfile a mile long. That got really hairy. I now try to avoid using clients. I go into it in great detail here: <a href="https://www.youtube.com/watch?v=dBO62A3XaSs" rel="nofollow">https:&#x2F;&#x2F;www.youtube.com&#x2F;watch?v=dBO62A3XaSs</a> and we&#x27;ve talked about this many times on trafficandweather.io if you want to learn more.

I think <a href="https://github.com/pksunkara/alpaca" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;pksunkara&#x2F;alpaca</a> is a good starting point. Given a web API, it generates client libraries in ruby, python, php and node.js

The Google APIs Client Generator is an awesome tool that automates this process. It takes a service description and generates a complete client library:<p><a href="https://code.google.com/p/google-apis-client-generator/" rel="nofollow">https:&#x2F;&#x2F;code.google.com&#x2F;p&#x2F;google-apis-client-generator&#x2F;</a><p>The service is defined in a platform-neutral discovery document, which can be used by any provider:<p><a href="https://developers.google.com/discovery/v1/reference/apis" rel="nofollow">https:&#x2F;&#x2F;developers.google.com&#x2F;discovery&#x2F;v1&#x2F;reference&#x2F;apis</a><p>There are generators for Python, Java, .NET, Objective-C, PHP, Go, GWT, Node.js, Ruby, and others.

<p><pre><code> Caching, throttling, timeouts, gzip, error handling. </code></pre> 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.<p>Why does every API owner have to write basically identical clients in every language out there?

Another reasons is that your API likely sucks&#x2F;is broken if you haven&#x27;t made a client for it (and thus figured out the gaps&#x2F;problems).

Fine, but you can&#x27;t provide clients for all languages and frameworks, so make sure your REST API is simple enough for those who need to make do without an official client library.

I think shipping your own client lib sort of defeats the whole point of REST as the &quot;one true way&quot; to build API&#x27;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.<p>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.<p>Also, client libraries don&#x27;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.<p>For example, I&#x27;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.<p>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&#x2F;when&#x2F;where HTTP requests happen and that isn&#x27;t always a good thing.

I wish clients would write themselves based on REST APIs.

&gt; You’ll have to mask GET requests with a HEAD request and appropriately handle HTTP status code 304 for resource not modified.<p>I&#x27;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?

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.

I think there&#x27;s another benefit here: edge cases will show up. I wrote a Python client for a company&#x27;s REST API which revealed an RFC bug during testing. From the source:<p>&gt; For POSTs we do NOT encode our data, as CompanyX&#x27;s REST API expects square brackets which are normally encoded according to RFC 1738. urllib.urlencode encodes square brackets which the API doesn&#x27;t like.<p>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.

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

It&#x27;s nice that this article claims everyone who makes an api should provide a client. But what happens when it uses hypermedia restful constraints? I think that any company which is able to provide multiple implementations for their API has already made it financially to afford those luxuries.<p>I know of some large companies which do this already, one of them being braintree, which offers an amazing API in many different languages, but they are already profitable and were bought by paypal.

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.<p>Two notes:<p><i>2)</i> No need to mask requests with a HEAD; a GET can also return a 304 directly.<p><i>6)</i> De-duplication of calls: Any method except POST should be idempotent already, hence also a retry-on-error is trivial in those cases.

While I agree with everything you say it leads me to the opposite conclusion that I should not roll my own half assed rest client.

Wow! 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:<p><a href="http://platform.qbix.com/guide/patterns" rel="nofollow">http:&#x2F;&#x2F;platform.qbix.com&#x2F;guide&#x2F;patterns</a><p>The Q platform was supposed to take care of the things that you have to do anyway when writing social apps.

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.<p>Maybe that just means writing a thin wrapper around one of these libraries specific for your API. But don&#x27;t reinvent the wheel every time.

Your API sucks and is not as idiomatic as you think if you can&#x27;t use curl as a client.

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&#x27;ve also missed the entire point of building a Rest API in the first place.<p>Your consumers should know how to handle HTTP requests from within their language. If they don&#x27;t, then no Client for your API will save them.

Not only should you include a client, you should write the client first.