[ps2000]

I guess it's also a matter of taste. In any case, my taste is this:

RESTful APIs usually represent CRUD operations, each of these letter can be beautifully mapped to request types: - CREATE -> POST - READ -> GET - UPDATE -> PUT - DELETE -> DELETE

Second point: {error: false, value: actual_data} If we have an error variable, what is the HTTP error code then good for? Normal Web Servers use the HTTP error codes for a reason. Besides using standard webframework a json containing only "actual_data" means less code, less errors and so forth...

Third point: URLs should represent the hierarchy: GET /users/43/bookmarks/32442?... is much more beautiful and straight-forward to work with than /api_handler.exe?user_id=43&bookmark_id=32442&operation=get...

Regarding authentication: use a secret API key, that's simple and secure. Everybody does that, from small services to multi million user services like facebook.

As a hint: read the dissertation of Roy Fielding who "invented" REST. In my opinion REST means to exploit HTTP as far as possible instead of using any custom conventions.

[SoftwareMaven]

I agree with most of what you said, but mapping CRUD directly onto the verbs is perhaps a little simplistic. See http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-res... for a discussion on it. The very short version is that idempotency is important, POST must be used for non-idempotent updates, and there is no reason PUT can't be used to create if you know the ID of the resource.

[poutine]

HTTP PATCH was created due to this problem, though I've not run across an API using it yet.

http://greenbytes.de/tech/webdav/draft-dusseault-http-patch-...

[SoftwareMaven]

The discussion here around the article I linked was my first introduction to PATCH. I would really like to see it implemented in Pyramid so my site can take advantage of it.