Why is REST API not RESTful?

MikeSchinkel

Hi SmugMuggers:

As someone new to SmugMug who will probably integrate it with client websites, I was really excited to see that you had a REST API. That is until I looked at it and realized that it is not a at all REST API, it is instead a RPC using POX over HTTP API (remote procedure call using plain old xml over http) with most of the negatives of RPC and few of the benefits of REST.

Now my guess is that you'll assume I'm being pedantic and that it really doesn't matter. But that is usually the case for concepts that have complex justification; until please learn about a concept they dismiss it as unimportant. IOW, ignorance is bliss.

Any chance you'd consider learning what being RESTful means and providing a truly RESTful REST API? Several ways to learn about REST:

• Ask on rest-discuss (Mailing List)
• Read RESTful Web Services (Book)
• Read Building Web Services the REST Way (Quick Start)

Minimally what you are doing is using verbs instead of nouns. Again, you probably think I'm being pedantic but there are very significant and tangible benefits to appreciate REST, especially for scalability and reducing load on servers, but it takes studying REST to really understand the benefits.

I hope you'll consider releasing a real REST API. If so, I'd be more than happy to help.

rkalla

Mike, let's use a specific example of the login REST response:

<rsp stat="ok">
  <method>smugmug.login.withPassword</method>
  <Login PasswordHash="$1$SzcXhAg5$ryhs7e5YPJjHPN2k4es3Y1" AccountType="Pro" FileSizeLimit="25165824">
    <Session id="f920524b60bdb9ec711bcdbb6efd3faa"/>
    <User id="512" NickName="frednerk" DisplayName="Fred Nerk"/>
  </Login>
</rsp>

Given what you were saying, could you properly REST-i-fy that response? I'm just fuzzy on how this isn't REST-y, and how to make it so

(I'm genuinly curious, I use the JSON API, but hear "REST" about 10x a day, so I figured I'd ask)

TerenceKearns.com

rkalla wrote:

Mike, let's use a specific example of the login REST response:

<rsp stat="ok">
  <method>smugmug.login.withPassword</method>
  <Login PasswordHash="$1$SzcXhAg5$ryhs7e5YPJjHPN2k4es3Y1" AccountType="Pro" FileSizeLimit="25165824">
    <Session id="f920524b60bdb9ec711bcdbb6efd3faa"/>
    <User id="512" NickName="frednerk" DisplayName="Fred Nerk"/>
  </Login>
</rsp>

Given what you were saying, could you properly REST-i-fy that response? I'm just fuzzy on how this isn't REST-y, and how to make it so

(I'm genuinly curious, I use the JSON API, but hear "REST" about 10x a day, so I figured I'd ask)

Look there "<method>" what does that tell you? That is a procedure. This means it is a remote procedure call. As far as I can remember (and it has been a while), rest is simple and doesn't encapsulate procedure requests using XML descriptors. The request is simply the GET or POST request - simple. No need for the overhead of well-formed and valid XML packets.

You should just be able to go

http://smuggler.foo/get_me_some_stuff/jason|PHP|xml|csv|whatever/?some=params
and you should get back a simple STRING that is consumable without the need for parsing through yet another layer.

Anything more than that is unjustifiable wastage. Programmer wastage, effort wastage, another place for a bug, and protocol overhead. The protocol overhead is signifigant when there are many ajax requests and latency matters.

It's so simple, when it dawns on you, it will be like a mack up-side the head.

devbobo

TerenceKearns.com wrote:

Ya gotta be kiddin me. Look there "<method>" what does that tell you? That is a procesure. This means it is a remote procedure call. As far as I can remember (and it has been a while), rest is simple and doesn't encapsulate procedure requests using XML descriptors. The request is simply the GET or POST request - simple. No need for the overhead of well-formed and valid XML packets.

You should just be able to go

http://smuggler.foo/get_me_some_stuff/jason|PHP|xml|csv|whatver/?some=params
and you should get back a simple packet that is consumable without the need for parsing through yet another layer.

Terence,

I think you will find that Riyad posted the response to a method call, not the request.

Cheers,

David

TerenceKearns.com

devbobo wrote:

Terence,

I think you will find that Riyad posted the response to a method call, not the request.

Cheers,

David

Yes, it looks like the response half of the remote procedure call unless I am mistaken. I am indeed guessing.
Is that a standard XML REST response (with just data) or is that an RPC protocol packet (with descriptors) that I need to parse?

I'm curious because I haven't had the chance to get into it yet.

devbobo

It's the standard REST response format...

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
	[xml-payload-here]
</rsp>

TerenceKearns.com

devbobo wrote:

It's the standard REST response format...

<?xml version="1.0" encoding="utf-8" ?>
<rsp stat="ok">
    [xml-payload-here]
</rsp>

Oh OK. I see, the method element is not part of some kind of protocol then, it is just part of the payload.

I didn't realise REST had a dedicated root element. I just thought it would be any old well-formed XML document.

Cheers.