Log in

No account? Create an account
entries friends calendar profile It's Me Previous Previous Next Next
The Autobiography of Russell
Life from a different perspective
REST: How to communicate request/response structure?
I think I need someone to explain something to me about REST.

I understand how it defines the URIs of communication by simplicity of existing, yet nowhere do I see any definition of or way of specifying what format or structure the data will be passed in. How do I know what I'll get back? How do I know what to send? Not just in JSON vs XML vs whatever else, but also in what elements or keys / values are inside either of those.

I could, theoretically, see using REST URIs in a SOAP WSDL, yet somehow I get the impression that's not what was intended (given how many 'REST kills SOAP' type posts I've seen around). So where do I define what is being sent back? How do I communicate that to someone who wants to consume my service?

Surely we can't expect everyone who uses REST to reinvent the wheel of how to communicate this basic information?

(Google+ Post)


8 comments or Leave a comment
vaelynphi From: vaelynphi Date: August 8th, 2011 04:48 am (UTC) (Link)
If I understand the ambiguity you're irked over, then I think the answer is something like this: it doesn't really matter, so long as the client of any request knows how to handle the data. Which is to say, results should probably be the same format consistently across a single site (or at least across a single context). The most useful idea behind the whole REST thing is summarized here:

"I assert that REST-ful URIs should identify a single resource. And different representations of that resource can be ‘negotiated’. e.g. via HTTP headers. I assert that things like language localizations, data formats, read only views, HTML forms, summary views, detail views, etc, are all just different representations of the same resource. I assert developers should work to keep all those representations on the same URI."

The other handy bit is using URLs that don't advertize the back-end: no .pl, .cgi, .asp, .php, or whatever extensions.

This is all really just the net catching up with what has been reasonable software design for decades.

But the like answer to your question, if I understand it, is to use the headers: if a sitewide convention isn't enough, then you can always pass appropriate headers for the content. In "RESTful" terms, this is Self-Descriptive Messages. A real fancy setup would, say, return SVG for modern browsers, but a (cached) PNG/JPG for older browsers and Internet Explorer, all at the same URI.

BTW, apparently the Flash 11 64bit beta fixes lots of issues with Flash in Linux; dunno about the 32bit version, but my videos went from always playing poorly, if consistently, to playing quite well, even in full screen, with only an occasional hiccup so far.
zimzat From: zimzat Date: August 8th, 2011 05:23 am (UTC) (Link)
?The question isn't so much the type of content as the format/structure of the content. Yes, image/etc can easily be figured out by the header. The question revolves entirely around JSON/XML/etc requests/responses: How do they/I know where the data they/I need is? There's no built-in description so we have to rely entirely on the developer to write complete and good documentation of return object structure and values?
vaelynphi From: vaelynphi Date: August 8th, 2011 05:38 am (UTC) (Link)
Rely on the developer... wait, isn't that you? ^.^

I dunno, but I do remember reading some SOAP vs REST articles and being 1000% confused, since the two didn't seem to be in competition. Perhaps I'm mistaking their more general philosophies for structural implementations?

Ideally, shouldn't you be able to rely on the developer to supply the data in either any format you request, or at least some general, accessible format (like JSON/XML/CSV/BBQ)? It would seem strange to me that someone would use a nonstandard format. Then again, I often dump returns to text just so I can feel around their structure when I'm unsure.

Perhaps you could describe a specific situation?
zimzat From: zimzat Date: August 8th, 2011 12:15 pm (UTC) (Link)
I think you're still missing my point. This is what I mean by structure: Will the response be like this:

{username: 'abc', lastActive: '2005-04-08 12:30:00', owner: 'bob'}
Or like this:
{Username: 'abc', Last_Active: '12:30:00 04/08/2005', Owner: 'bob'}
Or like this:
{username: 'abc', owner: 'bob', dates: {last_active: '2005-04-08 12:30:00'}}
Or like this:
{USERNAME: 'abc', LASTACTIVE: '2005-04-08 12:30:00', OWNER: 'bob'}

A lot of languages (PHP included) are case-sensitive when it comes to matching key names. If I recieved this JSON structure in PHP and decoded it as a regular PHP array I couldn't just do this if I didn't know which of the above the structure was in:

So, that brings me back to defining the structure in a consistent and easy to relay way.
vaelynphi From: vaelynphi Date: August 8th, 2011 04:21 pm (UTC) (Link)
Oh; well in that case shouldn't you have to rely on the developer?

I mean, I'm sure you could mangle the responses on the server-side to enforce a convention, but I'd hope in your line of business that you have access to the actual server-side development to be able to set a standard.

What I still don't get, though, is what this has to do with REST: wouldn't the particular format of each element be ambiguous regardless of what backend style of programming one used? REST specifies style guidelines for URIs, for instance, but so far as I know has nothing to say about what the code behind them is supposed to look like; indeed, I had thought the point of it was that it shouldn't matter. In other words, REST isn't meant to improve the programmer's life (in fact, it can make it really painful), but the user's.
zimzat From: zimzat Date: August 8th, 2011 04:32 pm (UTC) (Link)
Quite true, but many people set REST as a SOAP killer, yet with SOAP all someone has to do is point me at their WSDL and I can read exactly what they expect, point PHP's SOAP client at the WSDL, make the necessary function call off that, pass it the expected array parameters, and I'm done. All-in-one conveyence of protocol, standard, request, and response.

I'm considering this primarily from a user's or consumer's perspective. As the person implimenting it, yes, I have all the control in the world to do whatever I want to get it done, but then I still have to convey it to consumers.

I don't see how REST makes anyone's life easier except for very basic datasets and very basic data manipulation. How do I find a particular item in a collection without downloading the entire collection? How do I delete multiple items in a collection (without making O(n) calls to the server)? How do I update multiple items in a collection at the same time (again, without O(n) calls)? Answer is, you can't without custom interpretation of the REST rules, and so once again we're on the same par as SOAP with requiring some sort of documentation to explain the custom implementation, which will vary from instance to instance.
vaelynphi From: vaelynphi Date: August 8th, 2011 11:01 pm (UTC) (Link)
I think the REST vs SOAP people are smoking DOPE or something. They don't seem to have anything to do with each other at all. SOAP is about the protocol-layer: how is information exchanged or served; REST is about the client layer: how is information accessed. Either I misunderstand them both, or lots of people majorly conflate the two.

I think that if REST requires some kind of custom interpretation in order to provide these answers, it's probably because REST doesn't actually address those problems, and isn't meant to.

Since you brought this up I've read quite a few articles on these ideas, and so far none of them have made sense of the matter except this one: http://www.prescod.net/rest/rest_vs_soap_overview/ . Even then, it doesn't really spell out how the two are supposed to be adversarial.
zimzat From: zimzat Date: August 9th, 2011 12:55 am (UTC) (Link)
If it's not meant to answer those questions, then it's a half-baked idea or half-useful solution, so practically no one can be fully REST compliant and yet have anything beyond a basic data access application (Are they trying to model CRUD actions without the SQL language to make it flexible!?).

I'll try to review that website soon. I'm too hyped tonight to focus on reading that much.

Edited at 2011-08-09 12:56 am (UTC)
8 comments or Leave a comment