- Linked to that, a significant part of the documentation is about URLs to hit instead of being about document types
* Misuse of HTTP verbs, a lack of use (by going through POST for everything) would be bad enough but they go through GET which should be 1. safe (should not alter the server's visible state) and 2. idempotent (should be callable n times with the same parameters returning the same result, as long as the server's state was not changed). This API deletes things through GET.
* Lack of use of HTTP headers, instead of using the Accept header the client has to use an informally defined query parameter
* Lack of descriptive content types (linked to previous point)
* Complete absence of use of HTTP status codes (standard or custom), the API returns a status of 200 in all cases
This is pure and simple (and terrible, since it's over GET) RPC tunneled through HTTP.
I'd like to know the same thing. Aside from everyone complaining that they used the term RESTful wrong, is there anything really wrong? It authenticates securely over HTTPS so I am confused what is wrong. Saying it's not complaint I don't really follow either. Thanks for any help.
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.
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.
There are a few comments in this post that touch on the flaws of this API. Here's the gist:
1. HTTP methods are improperly used. The documentation states "All API calls should be sent as a GET HTTP request". GET is used to retrieve resources, and should be cacheable. It should NEVER change the state of a resource. Yet we see in that it's used to delete, create, and modify resources! Examples:
Two things to note: 1) no 'aspx' bullshit, that's implementation and shouldn't be visible to the user, and 2) the ID is in the URI itself as opposed to the params. URIs should seldom, if ever, change. Parameter names may change, URIs shouldn't.
3. Violation of content type retrieval. Let's say I want a folder as XML:
Note that I'm using the Accept header. This allows for flexibility in accessing my resource. With any luck, the server will give me an XML file, and its content type should be "text/vnd.sharefile+xml" (vendor specific content types are best).
4. No link relations in the body. I'm mostly assuming this because I haven't seen sample response bodies, but almost no one does this even though is a crucial aspect of a RESTful service. RESTful services describe the relationship between resources. Suppose I have an ordered collection of files. When retrieving a file, it should describe its relationship in this ordered collection. This is done either via the LINK header, or some sort of scheme in your response body (e.g. JSON Schema describes 'link' attributes).
What would be the RESTful way to specify jsonp? (i.e. wrapping the json response with a jsonp callback function).
A semi-related question - this is something I've wondered for a while - does the XMLHttpRequest single origin policy actually do anything for security? What kind of malicious resource might you try to fetch with an ajax call that can't just be wrapped in a jsonp callback?
That is possible (for stupid caches anyway, on purely technical grounds there should be no difference), it also looks much better to developers/users and is much, much easier to map/dispatch in most frameworks.
I was just talking about the restful part of the thing, your urls can look like this:
That may be so, however he asked what else is wrong with this API. An ugly URL scheme is something wrong with an API in my opinion and lots of people agree (see Rails, etc).
I thank you all for your great responses you have given so far. I meant my question in the restfulness way, but poutine adds best practice advises that I'm more than happy to also know about.
