To me there is nothing really wrong with this API except that they made the mistake of calling it a RESTfull API and, as such, have incurred the wrath of REST purists.

If they were to change the auth method to use a secret key for signing requests and just call it an RPC API then I don't think there would be a problem.

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.

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.

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-...

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.