So this whole thread could have been averted if the term REST was removed from this API it sounds.
How Not to write a "REST" API
61–70 of 117 posts
Re: How Not to write a "REST" API
#62What else is flawed with this API? I'd be nice to have a "Dos and Don'ts in REST API design", with the Don'ts exemplified with Sharefile's API.
* Not hypertext driven, all URL patterns are hardcoded and must be rebuilt. The one mandate of REST APIs is that they be hypertext-driven, this is a deadly sin: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
- 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.
Re: How Not to write a "REST" API
#63Earlier quoted context omitted.
> - 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). That is specifically one thing which does not apply and is completely irrelevant. Good-looking URLs have nothing to do with REST. The rest, yes.
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).
> That may be so, however he asked what else is wrong with this API.
He asked it in the context of API restfullness, as is pretty clear from the second phrase.
Re: How Not to write a "REST" API
#64What else is flawed with this API? I'd be nice to have a "Dos and Don'ts in REST API design", with the Don'ts exemplified with Sharefile's API.
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.sh…
Your second point really isn't RESTful - URIs should be opaque and "Servers must have the freedom to control their own namespace.":
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
Re: How Not to write a "REST" API
#65Earlier quoted context omitted.
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 r…
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-...
Re: How Not to write a "REST" API
#66Earlier quoted context omitted.
Yes, I can see how they got where they did, too... When all you have is a hammer, everything looks like a nail...
Engineers like us can be such snots sometimes. If as a culture we want people to build great RESTful apis and a company attempts to do so, public shaming isn't the answer. But. Their homegrown text serialization format is pretty wack. They couldn't just use CSV?
Agreed. I was mostly hoping to mitigate any conclusion that the design was a result of them being .Net developers. :)
Luckily there are some constructive comments in this post which point out some valid concerns. This is a good chance to share opinions and learn a bit. Unfortunately there are a lot of developers out there who are tasked with projects and have no one in-house with experience. I was in that boat and it took developing and maintaining a lot of bad APIs to learn what made a good one.
Re: How Not to write a "REST" API
#67Earlier quoted context omitted.
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.sh…
Your second point really isn't RESTful - URIs should be opaque and "Servers must have the freedom to control their own namespace.": http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
Thanks for the info! I love learning things :)
Re: How Not to write a "REST" API
#68Earlier quoted context omitted.
As someone just starting to learn about secure restful web services: what is wrong with this security implementation of theirs?
If you're learning about REST, do it right and make this book your bible - it's brilliant: http://www.amazon.com/Restful-Web-Services-Leonard-Richardso...
Re: How Not to write a "REST" API
#69Earlier quoted context omitted.
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.
Re: How Not to write a "REST" API
#70What else is flawed with this API? I'd be nice to have a "Dos and Don'ts in REST API design", with the Don'ts exemplified with Sharefile's API.
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.