Sacha Greif's Telescope [1] is probably the best open source HN clone I found, last time I checked.
Edit: I liked Telescope because it had a really slick (customizable) UI, persistent storage, and was a breeze to get up and running on Heroku.
What are you using node? You don't explain how to run the server at all. Not everyone knows how to use nodejs. Have you considered using a package.json [2] and publishing on npm?
Being a little pedantic here but your ReST API needs work, e.g. "/topic/add" is a bad API endpoint. Verbs are to be avoided. You got the POST part right, but you should be POSTing to a resource like "/topics/" or "/topic/", which is a list of topics. Take a look at "RESTful Service Best Practices" [3], it's a quick guide that should get you up to speed.
Edit: Downvoted? Really? I Give 3 solid points of constructive feedback here. If you disagree with something here please let me know.
>> Edit: Downvoted? Really? I Give 3 solid points of constructive feedback here. If you disagree with something here please let me know.
Probably because your tone was extremely aggressive. You think you provided feedback but it feels like you're trying to destroy the project. I'm not saying I thought that, but here's how it can be understood:
>> How'd you get upvoted so fast?
Sounds like "You're a fucking cheater, you gamed the system"
>> What are you using node? You don't explain how to run the server at all.
Sounds like "Using node is fucking stupid, and your doc sucks".
>> You got the POST part right, but you should be POSTing to a resource like.
It sounds like "What you built is crap because you didn't follow the X 'best' way of doing REST queries".
-----------------
Maybe it's because english isn't your main language. You could be geniously giving good feedback but it just doesn't *sound like it.
Maybe instead of:
>> What are you using node? You don't explain how to run the server at all.
it could be:
Why did you decide to go with Node? By the way, it would be great to have some documentation on how to start the server.
To me it seems you are reading what you want to read.
His criticism was legitimate, there is no reason to waste time nor energy on his "tone-of-writing". If his points are valid then that should be sufficient. Replies like yours contribute nothing.
I was answering his question of why he was getting down-voted, no more no less.
>> If his points are valid then that should be sufficient.
In theory, yes, in the real world, appearances matter. Being right is only one part of the equation.. if you can't convince the other person then it doesn't really matter whether you're right or not.
If you're giving feedback and it sounds like you're demolishing someone, chances are your feedback won't be listened to. It's not the end of the world, obviously, but you're losing your time and the readers too.
>> His criticism was legitimate, there is no reason to waste time nor energy on his "tone-of-writing".
The irony here is how by not having the right tone his feedback weren't understood correctly, and hence wasted the time and energy of most readers.
I can't speak for the GP, but I also tried the demo and I did find the design sleek and appealing.
But when I clicked the comments link on the first post on the front page, it took about 20 seconds to see the comments. Also voting for a comment made the page unresponsive for about a second.
I don't know if this is because just the demo server, the underlying technology or lack of optimization in the actual app, but this is what made the otherwise cool demo less interesting to me.
I might attract a lot of flack here for saying this, but lobstr.es is a lot HN could have been, alas it is yet to get some serious amount of participation.
How do you even get an account there? Is it really strictly invite-only or is there some sort of a waiting list? The topics on the front page seemed to interest me, I'd give it a try if there was a waiting list.
Well, I think the whole self-selection on who can participate has a lot to do with that. I wonder if might've been enough to simply sell accounts/memberships at this point?
Their being invitation only and their policy of holding users responsible for anyone they invite suggests they want as little participation there as necessary.
Forgive my lack of knowledge of ReST, but why is "/topic/add" a bad API endpoint, and why should verbs be avoided? How else would you get the "Add Topic" form?
`/topic/add` would be a fine URL to return the form HTML, the "RESTful" API would be like `POST /api/topic` where POST implies create and topic implies, well, topic.
Often the best approach is to have e.g. /topics be both the API endpoint and the web endpoint for the collection of topics resource and e.g. /topic/<identifier> be the endpoint for individual topic resources.
In both cases the server loads the same data, but if the negotiated content type is text/html then it renders an HTML template with the data and returns a page showing a (probably paginated) topic list along with a form for posting a new topic (possibly hidden and revealed by javascript on a button click, etc).
The form would POST to the /topics endpoint which would create the new topic and then return a redirect to the /topic/<identifier>. Another form might also allow replacing existing topics by PUTing to a /topic/<identifier> endpoint. Or via PATCH for use via AJAX.
The actual /topic/<identifier> links in both the HTML and JSON views would really be something like /topic/<id> or /topic/<uuid> or /topic/<slug>. Again, if you click on one of the topic links in the HTML view in a browser then when you land on the individual topic link it will also negotiate the text/html content-type and you'll get the topic detail page, etc.
If you have pages like "most recent topics" or "trending topics" etc they could be mapped to separate collection resources like /topics/recent, /topics/trending, etc that are just projections of the appropriate subset of the overall collection resource.
If the negotiated content-type of any GET request is application/json (or e.g. application/edn) then it returns the API results in the appropriate format. If you follow one of the same links served from the JSON file from your API client, then it will again negotiate application/json and it will get the JSON version the topic detail. The JSON results might be in a format like http://stateless.co/hal_specification.html.
In the PDF he points out it says "Resource names should be nouns—avoid verbs as resource names. It makes things more clear. Use the HTTP methods to specify the verb portion of the request."
However the same PDF, in the very same section, states "Having sensible resource names or paths (e.g., /posts/23 instead of /api?type=posts&id=23) improves the clarity of what a given request does."
To me - having the verb in the resource name is very sensible specifically because it improves the clarity of what a given request does (or at least is intended to do).
And as a personal style thing, I usually put the verb first (it reads more like English that way) so I would have gone /add/topic -- but again that's just a personal style/organization thing.
The whole idea behind REST resources, though, is that the HTTP method expresses the action, and the URI identifies the object acted upon. In that conceptual scheme, there is neither need nor place for verbs in the URI; POST /topics/add is redundant, because POSTing to a collection already has the semantic value of "add an item to this collection". Similarly, if you're modifying an existing item, you don't need to PUT /topics/23/edit or what-have-you; PUT already means "replace the existing content with the request body I'm sending", so all else that's required is to identify the particular content to replace, for which /topics/23 suffices. Having the HTTP method and the endpoint gives you all the clarity you need in terms of what a request does, and to which thing it does it.
An additional, and very non-trivial, benefit of this scheme is that it is standard and discoverable: "standard", in the sense that these basic HTTP operations are defined in RFC 2616 and exhaustively documented there; "discoverable", in the sense that knowing some endpoint represents a REST resource API instantly tells you quite a lot about how you can interact with it, and you can find out the rest from the responses you get when you make API requests -- which responses RFC 2616 also explains how to interpret.
Not everything is simple. REST resources are, and they need not have a complex API. Poorly thought-out APIs for simple things require a lot of documentation, that mostly being lousy explanations of the interactions between an incomplete set of edge and corner cases. Well thought-out APIs for simple things barely require any documentation at all.
The REST resource API is a sterling example of the latter sort; once you're familiar with RFC 2616, you can discover everything else you need from the responses you get to API requests. This is not so when redundant verbs -- POST /topics/add -- are used in a backwards namespace -- POST /add/topic -- with uncertain naming -- /add/topic, so if I want all topics do I GET /topics or /topic, or /get/topics, or what? What makes all this confusion more worthwhile than just using REST resource endpoints? Do you want people who consume your API to curse your name for making them deal with a bunch of needless impedance matching, or to effortlessly retrieve what you're offering and do something amazing with it?
I agree that the HTTP methods, when used properly, express the action...the problem is A. not everyone actually follows that properly and B. the HTTP method isn't always immediately obvious to people working with the service (i.e. newbie devs.)
Having the verbs in the URI is not DRY (so that kind of sucks) but really it's not very damaging either...and so I believe the upside of (human readable) clarity outweighs the downside of a tiny bit of redundant expression.
In the end, unfort. because so many don't follow RFC 2616, devs are forced to read/pay attention to the documentation for a given service anyway (at least that's always been my experience)...so in a perfect world, I would agree verbs are the methods (and not needed in the URI)...but we are a ways off from a perfect world still...
It is entirely reasonable to expect newbies to read the relevant documentation; if someone can't be bothered to read and understand one relatively succinct RFC, then any difficulty he experiences in consuming my API leaves me entirely unmoved. As hurdles go, that one's so low it's practically buried; if he can't be bothered not to stub his toe on it, how's he going to handle himself when he gets to something that requires actual effort?
Someone else doing it wrong doesn't excuse you doing it wrong as well. How do you expect anything to get better if you won't turn your own hand to making it better? Sooner or later, someone will use your implementation as an example for her own. It is therefore very much worth your while to ensure that the example you provide is one of how to do it right.
I think it depends on your intent behind the API. Are you trying to create something that makes the developer/user/world easier and better or are you trying to keep your system perfect, clean, and done the right way?
If it's about opening up to the larger world so that more things can be built and accomplished, you want to make it as easy as possible to use and understand across the board.
You can be as strict and stern about RFC specks and rules as you want when building your thing...however, the more rigid you are, they more you'll need to be operating from a position of power from the start or the more you'll struggle to get real adoption (and to be realistic, most of us are not really releasing things from a position of power)
... though obviously the real thing isn't open source, as pg and kogir have made numerous changes they're not releasing and AFAIK they're not taking pull requests on news.ycombinator.com (but they do have a bug tracker @ https://github.com/HackerNews)
Odd that in all this time no one seems to have forked the original code and iterated on it. Deployed it, sure, but not (say) fixed any of the bugs that annoy people about HN, or made it better.
It's a trivially simple program, written in a dead-end language, has a ridiculous architecture, and there appears to be no prospect of changes to the open source version being propagated to the production HN. Doesn't seem particularly odd that nobody has forked the code. If you want to run a site like this, writing a clone seems like the rational choice.
Sacha Greif's Telescope [1] is probably the best open source HN clone I found, last time I checked.
Edit: I liked Telescope because it had a really slick (customizable) UI, persistent storage, and was a breeze to get up and running on Heroku.
What are you using node? You don't explain how to run the server at all. Not everyone knows how to use nodejs. Have you considered using a package.json [2] and publishing on npm?
Being a little pedantic here but your ReST API needs work, e.g. "/topic/add" is a bad API endpoint. Verbs are to be avoided. You got the POST part right, but you should be POSTing to a resource like "/topics/" or "/topic/", which is a list of topics. Take a look at "RESTful Service Best Practices" [3], it's a quick guide that should get you up to speed.
Edit: Downvoted? Really? I Give 3 solid points of constructive feedback here. If you disagree with something here please let me know.
[1] http://telesc.pe/
[2] https://www.npmjs.org/doc/files/package.json.html
[3] http://toddfredrich.com/restful-best-practices-v1-1.html