Substitute "XML" for "JSON" and we've now come full circle.<p>The point about REST is that it is self-describing. And ideally should be using the same URIs as the version people clicking around in Firefox or Chrome see. The API is just the XML or JSON or whatever is flavour of the week version of the HTML version.<p>(Or we could use embedded data—microformats, microdata, RDFa—and get rid of that distinction.)
Sigh. This is optimizing for the wrong problem.<p>Stop creating REST APIs that are only level 1 or 2 (see <a href="http://martinfowler.com/articles/richardsonMaturityModel.html" rel="nofollow">http://martinfowler.com/articles/richardsonMaturityModel.htm...</a> ).<p>Start writing HATEOS systems where the client is coupled to the semantic rather than the syntax.<p>Machine parseable interface descriptions might get rid of some boilerplate but it doesn't make for a more robust client-server relationship.
We could give a name to the language we use to define such files. It's a language that defines Web services, so perhaps Web Services Description Language? :-) <a href="http://en.wikipedia.org/wiki/Web_Services_Description_Language" rel="nofollow">http://en.wikipedia.org/wiki/Web_Services_Description_Langua...</a><p>Flippancy aside, maybe there's a need for a next generation of this that skips all the XML headaches after all.
I don't see how writing JSON REST API descriptions isn't practically the same as writing REST API clients anyway: they're still clients, just written declaratively rather than procedurally.<p>If the point is "stop writing procedural REST API clients and write them declaratively instead" then that advice is by no means restricted to REST API clients.<p>If the point is "hey, I noticed that REST API clients are another thing that we can now comfortably write declaratively" then OK.
This article is not at all about REST, it is about RPC and its shortcomings. These shortcoming were fixed by REST, and the author of the article rediscovers these fixes.<p>A key features of a REST API is that is self describable, in a sense, that it has a single entry point from which a generic client can automatically discover available resources and actions. APIs in the given examples are not like this, they require custom clients that are strongly coupled with an application. These are not REST APIs but RPC APIs.
All that these sorts of description produce is a low-level API. That can be useful, but what's really needed are high-level APIs that provide meaningful semnatics:<p><pre><code> my $me = Facebook->new( username => 'autarch' );
$me->post_status("I'm on Hacker News writing this comment");
my $friend = Facebook->new( username => 'imaginary' );
$me->post_on_wall( $friend, "Hey buddy, I am on Hacker News writing this comment" );</code></pre>
swagger (<a href="http://developers.helloreverb.com/swagger/" rel="nofollow">http://developers.helloreverb.com/swagger/</a>) has been doing whats proposed here. By describing your APIs with swagger-spec you get a beautifully documented APIs, code generation of client libraries and some more stuff: <a href="https://github.com/wordnik/swagger-core/wiki/Downloads" rel="nofollow">https://github.com/wordnik/swagger-core/wiki/Downloads</a>
Hmmm....JSON documents (jsonSpec) describing the restful services is the new WSDL, feels like 2002 all over again.<p>I think too many people consume REST APIs in different manners, utilizing different data in unique relations. This is the beauty of it.
We've been experimenting with this at my office. We use yaml descriptions of all of our routes to generate test coverage. We plan to later generate our documentation and client libraries with the same docs.<p>Document-generated server behavior is something we're researching as well, to possibly represent business logic. We're hoping that patterns can be found and condensed into notations, like Regular Expressions do for string-parsing. We'll post about anything that we come up with.<p>One of my side projects us an Ajax library which allows javascript to respond to requests (LinkJS [1]). It has a helper object called the Navigator, which is like a miniature Web Agent. It retains a context, and uses the Link header from the response to populate the navigator with relations. It works out like this:<p><pre><code> var nav = Link.navigator('http://mysite.com');
nav.collection('users').item('pfraze').getJson()
.then(function(res) {
console.log(res.body); // => { name:'pfraze', role:'admin' ...}
})
.except(function(err) {
console.log(err.message); // => 404: not found
console.log(err.response.status); // => 404
});
</code></pre>
The advantage is that the link header is a relatively condensed representation of the resource graph. As a result, it's not a problem to send it and process it every time. You do gain latency, but the internet is only getting faster, and caching can be used. Meanwhile, the server can rewire links without interrupting their clients.<p>1 <a href="https://github.com/pfraze/linkjs" rel="nofollow">https://github.com/pfraze/linkjs</a>
Isn't this what <a href="http://json-schema.org" rel="nofollow">http://json-schema.org</a> aims to provide? Or am I missing something. It's a solid spec.
While I agree with the title, I am not so sure about the solution presented. HATEOAS, whether encoded in JSON or XML, can only give you so much information about the semantics of links.<p>IMHO, what's needed is better support for "generic" REST in programming languages and/or libraries. Objective-Smalltalk (<a href="http://objective.st" rel="nofollow">http://objective.st</a>) features "Polymorphic Identifiers", which make it possible to both interact directly and abstract over web interfaces.<p>To reference a URL, just write it down:<p><pre><code> news := http://news.ycombinator.com
</code></pre>
Arguments can be added without string processing:<p><pre><code> #!/usr/local/bin/stsh
#-zip:zipCode
ref:http://zip.elevenbasetwo.com getWithArgs zip:zipCode
</code></pre>
This is a file downloader, similar to curl:<p><pre><code> #!/usr/local/bin/stsh
#-<void>scurl:<ref>urlref
fileComponent := urlref url path lastPathComponent.
file:{fileComponent} := urlref value.
</code></pre>
For abstraction, you can build your own schemes, either directly in code or by composing/modifying other schemes. For example, if I want to look up RFCs, I can define the rfc scheme:<p><pre><code> scheme:rfc := ref:http://datatracker.ietf.org/doc asScheme
</code></pre>
Or I can compose schemes so the rfc scheme looks in a bunch of different places (memory, local directoy, several http/ftp servers).
This is essentially trying to solve the same problem as Swagger. Swagger is "a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services" [1]. Check out the spec on GitHub here [2].<p>[1]: <a href="http://developers.helloreverb.com/swagger/" rel="nofollow">http://developers.helloreverb.com/swagger/</a><p>[2]: <a href="https://github.com/wordnik/swagger-core/wiki" rel="nofollow">https://github.com/wordnik/swagger-core/wiki</a>
There is a lot of talk about this idea being SOAP-like, but I disagree.<p>SOAP was insane and its counterpart, WSDL (which is really the part that is most comparable to this idea), was even more insane.<p>But, the basic premise was not bad. It was the execution which sucked by trying to account for every situation, adding namespaces, etc. And if you ever worked with language libs designed to interface with SOAP/WSDL, it would make you slap a bunny.<p>With this idea, however, adding an optional JSON-based descriptor language could be helpful. Key would be to keep it simple, allowing the bare mnimum number of data types, with one simple array structure for collections. Allow object definitions with an infinite number of nesting levels, and that would be it. I wouldn't even get into optional vs required stuff, validation, etc. That stuff should stay at the application level. Why stuff it into the interface layer?<p>From there, it would be easy to develop libraries to generate clients in any language for any API just by feeding it the JSON descriptor. Or (as I think the author intended) just use one universal client that any app can use. For languages that aren't strongly typed anyway, the latter would be fine.<p>Someone mentioned that it would require the server side devs to keep the descriptor in sync with the code. No biggie for apps that already offer client libs in different languages and must keep them up to date anyway. Not to mention there should be some doc that needs to be kept in sync (REST is not typically self documenting in reality).<p>In any event it wouldn't be required. What would be the harm in creating a standard for those apps that choose to use it?
Can't we just stop writing clients for specific REST API:s period and rather just build one good API client that can easily be extended and adapted to any API?<p>That's the path I've been using in all projects lately - because frankly - I don't want to deal with a bunch of different API clients for Twitter, Facebook, Soundcloud, Instagram or whatever sites it is that I integrate with - all those different syntaxes and all that duplicated code etc doesn't help me - I want all of their individual differences hidden away for me and colleagues behind a single well known syntax which I myself can extend to expose the resources and methods that I need - like if I need it a method for posting a photo for the API:s that support that and so on.<p>My advice today would be: Pick a good HTTP client, preferably with good OAuth support, and then build your own extendable API-client on top of that and integrate all the different API-resources you need with that client whenever you need them.
A client template library for REST API need to be Turing complete, otherwise it will be too weak to be able to handle complex services or complex client-side tasks, such as caching, dependency relations, data that span multiple services etc. Even if you make the template library simple, you'll need to wrap that with a layer of complex code. All you've done will be adding another layer on your code. You could re-design your code to fit a manageable design, but server side of the REST APIs are usually design by others whose priority is the code on the server side. So, by definition of the very task, the REST API client code have to be a complex soup where the client considerations mix up with those of the servers'.
While I understand the allure of writing specs and using a unified library, good API clients are more terse, as they're written to take advantage of the programming language you're using, and understand the particulars and idioms of the API they're written against. For example, the client might pick up the correct environment variables for your API credentials, or reduce certain repetitive code.<p>Another example: I wrote a client that returns a queue message. Attached to that message are some helper methods for deleting, releasing, and touching the message. It makes your code cleaner and easier to understand.
I think Google is already doing this using a form of JSON-Schema:
<a href="https://developers.google.com/discovery/" rel="nofollow">https://developers.google.com/discovery/</a>
Given that the prevailing sentiment is that REST is self-describing and the API description doc is unnecessary, are there any examples of client generators that work directly off of a REST service?<p>I'm curious how this works in practice. What about authorization and parts of the API that are only available to certain users, does the client generator need to be authenticated? Are there standards for describing the meta-data associated with URLs (validation, optional parameters, etc.)?
The article fails to mention the existing JSON Schema and JSON Hyper-Schema standards that he is advocating: <a href="http://json-schema.org/" rel="nofollow">http://json-schema.org/</a><p>Both are currently used by Google's public APIs to auto-generate clients. Ruby/Python clients load the schema docs at runtime and do method_missing magic, Java/.NET clients generate static typed libraries periodically.
There is for example RestTemplate from Spring for Java/Android apps, which solves this problem.<p><a href="http://static.springsource.org/spring-android/docs/1.0.x/reference/html/rest-template.html" rel="nofollow">http://static.springsource.org/spring-android/docs/1.0.x/ref...</a>
I've gone a step further and converted the JSON definition into JavaScript method calls: <a href="https://github.com/olegp/restwrapper" rel="nofollow">https://github.com/olegp/restwrapper</a><p>RPC FTW ;)
So we solve the problem of too many REST clients via another REST client? I agree with ttezel, and unio does look pretty cool, but I got a chuckle out of this :)
I wrote a quick port to PHP that is installable via Composer. <a href="https://github.com/andruu/unio-php" rel="nofollow">https://github.com/andruu/unio-php</a>