I like the idea. This is useful to generate stubs.
Stop Writing REST API Clients
81–90 of 137 posts
Re: Stop Writing REST API Clients
#82This 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. 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…
In what way is REST self-describable? REST is not a standard, but rather a widely accepted convention.
I have seen a few RESTful servers self-describe, (ie. GET /api/v1/ returns ['/users', '/posts']). However you can't claim this is a key feature of REST clients because there is no agreed-upon standard to have services describe themselves. HTTP is not sufficient.
If there were a real standard here, we would not have this problem. Like it or not, everybody is calling their custom API a 'REST' API nowadays, and without a real standard, nobody is wrong.
Re: Stop Writing REST API Clients
#83I think Google is already doing this using a form of JSON-Schema:
https://developers.google.com/discovery/
Re: Stop Writing REST API Clients
#84Isn't this what http://json-schema.org aims to provide? Or am I missing something. It's a solid spec.
Personally I'm partial to http://jschema.org/ (also see http://jschema.org/rpc.html) because it seems simpler.
My naive impression is that JSON-Schema is trying to be just like XML Schema, but in JSON. Which doesn't seem like a good thing.
Re: Stop Writing REST API Clients
#85Am I the only one who doesn't like receiving direct orders from article titles?
No, I got quite mad when I read the whole promotional article for his new node.js program without seeing a single argument against REST APIs.
Re: Stop Writing REST API Clients
#86Hypermedia APIs are an approach to solve this problem. It essentially does what you did, and add some other benefits like de-coupling URIs.
Really? Seems to me like Hypermedia APIs should move the problem from the wire protocol to the application protocol?
Hypermedia says "oh yeah, here's some markup, look there are URIs in it". For a human user, we're like "cool, I'll try and click these, see what they do".
But software is going to want "um...okay, how to I parse this markup, and how do I generate the submissions you want? And, okay, you can change URIs, but please don't change anything else about that operation, or I will break completely. That's right, we're not really decoupled."
So, even with hypermedia APIs, AFAIK you're still going to want some marshaling to/from host language. ...and so you're back to having a spec, and coupling, you've just moved it around.
(Rant on coupling, people seem to think it's always bad and you can make it go away. Reality: you can't make it go away, and sometimes just accepting it directly is a whole lot simpler than deceiving ourselves about it's existence by over-applying abstractions.)
Re: Stop Writing REST API Clients
#87Substitute "XML" for "JSON" and we've now come full circle. 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. (Or we could use embedded data—microformats, microdata, RDFa—and get rid of that distinction.)
Yes my argument is simply that we publish API specs in a machine-readable format to avoid wasting time implementing clients repeatedly. WSDL and WADL had good intentions at heart, but XML is ugly. JSON is nice since it's human-readable and light. Why not publish JSON versions openly for REST APIs, reducing implementation cost for clients?
XML is more human readable than JSON, to my eyes.
Re: Stop Writing REST API Clients
#88This 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. 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…
In what way is REST self-describable? REST is not a standard, but rather a widely accepted convention. I have seen a few RESTful servers self-describe, (ie. GET /api/v1/ returns ['/users', '/posts']). However you can't claim this is a key feature of REST clients because there is no agreed-upon standard to have services describe themselves. HTTP is not sufficient. If there were a real standard here, we would not have…
REST architecture was introduced by this paper https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
'Semantics are a by-product of the act of assigning resource identifiers and populating those resources with representations. At no time whatsoever do the server or client software need to know or understand the meaning of a URI -- they merely act as a conduit through which the creator of a resource (a human naming authority) can associate representations with the semantics identified by the URI. In other words, there are no resources on the server; just mechanisms that supply answers across an abstract interface defined by resources. It may seem odd, but this is the essence of what makes the Web work across so many different implementations.'
Re: Stop Writing REST API Clients
#89Am I the only one who doesn't like receiving direct orders from article titles?
No, I got quite mad when I read the whole promotional article for his new node.js program without seeing a single argument against REST APIs.
That's because the article does not argue against REST APIs. It argues against coding wrappers for them and instead proposes a solution that allows you to define API specific behavior in JSON and use one library to rule them all.
Re: Stop Writing REST API Clients
#90Ha. So, now we're back to SOAP and WSDL's.