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,
esjewett
· 10 months ago
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.
Dick Hirsch
· 10 months ago
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_doc.html) to determine the format - which is a good idea in my opinion.
Instead of DESTROY, use "DELETE". Instead of "UPDATE" use "PUT".
D.
esjewett
· 10 months ago
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.
All Comments
(but there are no DESTROY or UPDATE methods in HTTP http://www.w3.org/Protocols/rfc2616/rfc2616.html)
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,
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_doc.html) to determine the format - which is a good idea in my opinion.
Instead of DESTROY, use "DELETE". Instead of "UPDATE" use "PUT".
D.
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/REST+API+Documentati...). I'd be interested in if there are other options.