esjewett.com - Latest Comments in A RESTful ESME API

Re: A RESTful ESME API

esjewett — Sun, 15 Feb 2009 09:06:27 -0000

Thanks!

I agree with you on the format issue. I'm partial to the id.format approach. That's not really a component of REST vs. RPC though, so I thought I'd leave it out for simplicity. If we're talking about fully specifying an API then it needs to go in, for sure.

I'm not very familiar with how long-polling works. I assume that we need to communicate to the server that it needs to keep the connection open for some period of time. There are two ways I can think of communicating this need without creating a separate API resource.

You could use an extra parameter in the GET request to tell the server that you wanted to long-poll, or to specify some sort of time-out (?timeout=5min). This isn't very RESTful since this parameter isn't really an attribute of the resource.

You could also use the HTTP If-Modified-Since header to specify a time a few minutes in the future. This would require client and server clocks to be synced up, and the server would have to be smart enough to figure out that future=long-polling.

Yes, I stole both of these ideas from the Twitter API (http://apiwiki.twitter.com/.... I'd be interested in if there are other options.

Re: A RESTful ESME API

esjewett — Sun, 15 Feb 2009 09:01:15 -0000

Right, the fact that I'm not an expert at this stuff shows, doesn't it? :-) You and Richard are exactly right that it's "DELETE" and "PUT" instead of "DESTROY" and "UPDATE". I'll make the change.

Re: A RESTful ESME API

Dick Hirsch — Sun, 15 Feb 2009 04:49:45 -0000

Great blog.

One question: how would you distinguish between long-polling and normal GET api/users/USERID/messages call?

Format is also an issue. Yammer uses "id.format" (http://www.yammer.com/api_d... to determine the format - which is a good idea in my opinion.

Instead of DESTROY, use "DELETE". Instead of "UPDATE" use "PUT".

Re: A RESTful ESME API

jmettraux — Sun, 15 Feb 2009 01:13:09 -0000

Very nice, way to go !

(but there are no DESTROY or UPDATE methods in HTTP http://www.w3.org/Protocols...

Don't forget to provide a service document (à la AtomPub) and then to provide hyperlinks between the various representations, thus an HTTP client would simply "enter the API" via the service document and then discover via the links (rel="xxx") the various services available.

Actually links are more important than URI hierarchies (it took me a while to understand).

Best regards,