1,214 karma · joined November 6, 2008
When Rails starts including a messaging stack, job server, and more, then I'd be right behind you in your complaint.
UPDATE: More on this here http://blog.izs.me/post/3295261330/on-npm-and-homebrew
Sublime Text 2 is pretty great (http://www.sublimetext.com/2).
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...).
"""You don’t have this problem with chat transcripts. Forcing people to reduce their otherwise rambling thoughts into concrete sentences helps focus discussion, too.
We’ll have meetings at GitHub, but I can count the number of full “meetings” we’ve had in the last year and a half on one hand."""
The former bit implying that the focus of sentences helps, the latter bit implying to keep the membership of the meeting to only those required.
Again: siloing is far more toxic than meetings in my experience. It's far too easy for a dev to wander down a path that has no value when operating in a silo. Agile tells us that we need to exist in a state of constant communication and feedback. This necessitates meeting with people in some fashion.
Good luck! I hope it brings you success.
Additionally, marketing likes to see the major number change (the "X" in the X.Y.Z). I think the public does too. They feel like they're getting more bang for their buck.
In said project we had a number of modifications to libraries to support some additional desired functionality. The developers at the time simply forked the library and wrote patches on top of the mainline branch. We found this significantly impeded our ability to upgrade, or take advantage of changes, down the line, as well as to track upstream's HEAD. When one forks, branches, and then patches on the branch, these problems are easily skirted. In addition, it's easy to submit your patches for integration into upstream.
In the end the gain is flexibility. One cannot discount the value of flexibility.
I understand that syntax may be more convenient for some, but this is indirection, and is a source of complexity that may impede collaboration from other devs more familiar with JavaScript.