How Not to write a "REST" API

"API method urls are all the same .aspx, regardless of method used"

Isn't it more the fact that they spend all of their efforts documenting the URI structure and very little on the media types used - which is very unRESTful.

From a quick glance:

- Doesn't use HTTP verbs (GET, PUT, POST, DELETE) to retrieve, modify, create and remove objects.

- Doesn't use a restful url path to action on (ie. GET /users/#{user_id} to get a specific user by id, POST /users to create a new user).

- Doesn't use HTTP codes to return results (ie. HTTP 200 for normal operations, 201 for created, 40x for error conditions).

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'm with you on just knowing we can do so much better. Some of the RESTful HATEOS based APIs coming out are simply beautiful. However,

    - API method urls are all the same .aspx, regardless
    of method used

Extensions are meaningless. That is why we have Accept/Content-type headers. The HTTP spec even explicitly says to not use extensions to relay content information between client and server, from what I recall.

    - All calls are sent as GET (ignoring the whole point
    of HTTP methods in REST)

I haven't read Fielding's dissertation in a while, but using the "Coles Notes" version from Wikipedia, I do not actually see using the verbs a requirement for REST. I do not recall REST even requiring HTTP. You can use any protocol you want, so long as it conforms to the principles.

RESTful, on the other hand, does specify the use of HTTP verbs, but the site in question makes no mention of being RESTful.

By not using the proper verbs, the site does appear to violate the caching rules of REST though, I'll give you that.

    - Custom authentication putting credentials in URL
    or in headers (neither of which are encrypted over
    https)

The entire https payload is encrypted, headers and all. REST says nothing about how authentication should be implemented.

    - Return format is done with get arguments instead
    of HTTP content negotiation in headers (not so bad)

This falls under the same as using extensions. Though I will agree with you that it is a reasonable compromise in some cases, such as using a browser where you can't reasonably set your own headers.

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:

GET https://subdomain.sharefile.com/rest/folder.aspx?op=create...

GET https://subdomain.sharefile.com/rest/file.aspx?op=delete

These should be as follows:

POST https://subdomain.sharefile.com/rest/folder.aspx

DELETE https://subdomain.sharefile.com/rest/file.aspx

HTTP verbs have specific semantics that allow for intelligent, scalable architecture.

2. Individual resources are not identified by an unchangeable URI. Let's say I want a folder:

GET https://subdomain.sharefile.com/rest/folder.aspx?op=get&...

Nope. This is more RESTful:

GET https://subdomain.sharefile.com/rest/folder/123

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:

GET https://subdomain.sharefile.com/rest/folder.aspx?op=get&...

Wrong. This is the request I should be sending as a curl:

curl https://subdomain.sharefile.com/rest/folder/123 -H 'Accept: text/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).

A pretty good RESTful API is Github's (see http://developer.github.com/). If you'd like to learn more, I highly recommend "REST in Practice" by Webber, et al (http://www.amazon.ca/REST-Practice-Hypermedia-Systems-Archit...).