Re: REST API questions

[Nelson Minar <nelson@xxxxxxxxxx>]

This discussion is really helpful for me in clarifying the REST
proposal. I hope it's useful for others, too!


Joe, one more broad question that came up in reading your reply: how
do I uniquely refer to entries in your REST API proposal? I gather
it's from the URI for the entry:
  HTTP/1.1 201 Created
  Location: http://example.org/reilly/1

Several blog engines (Blogger, I think Movable Type?) don't really
have a single-URI-per-entry model. Or they do, but the URI includes an
anchor to be unique:
  http://www.blogger.com/developers/2003_07_01_archive.pyra#105711794730830300
I've always thought this was a bad way to do permalinks, but it's
common practice.

Does this pose a problem for using URIs to identify entries? HTTP
clients don't send the stuff after the #; they use it locally to find
the point inside the file. So if my HTTP client sends
  http://www.blogger.com/developers/2003_07_01_archive.pyra
when trying to do an update/delete, how will the API know which post I meant?


On to your reply:

>>   Blog does not exist
>Return 404 since that URI identifies the blog, or more appropriately 410 
>if they got Jon Robb'd.

How do you distinguish the "404 there's no API server at that URI"
from "404 you found the API server but there's an application level
error about the location of the blog"? I know it's central to get this
stuff right in REST, but I don't know how.

To take your example:
  http://dev.example.net/api?userid=reilly&action=create
If a client gets a 404 does it mean there's no API at
http://dev.example.net/api? Or does it mean there's no user "reilly"?


> >   Post with that ID already exists
>This can not happen in the REST form of the API.

Is this because your proposal doesn't put the entry ID in the upload?

I fear this will be a bit tricky in Blosxom; blog entries are
filenames are URLs, so when I create a new entry I'm going to want to
specify the URI. Ie, I want to create
  http://www.nelson.monkey.org/~nelson/weblog/culture/games/Tron20.html
The fact that it's named "Tron20" is important to me - how do I tell
the create API what this name is?


> >   Post with that ID does not exist (on delete)
>This is not an error in the REST form of the API. Each entry has it's 
>own URI and DELETEing a resource returns a 200 on success whether the 
>resource existed at the time or not.

I think this is a mistake - it's important when a user tries to delete
something to tell them whether the delete succeeded or not. One kind
of failure is "the thing you tried to delete doesn't exist".


APIs are hard!
  Nelson