diff --git a/LICENSE b/LICENSE index 2823c8e..c565a55 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2014 Y Combinator Hacker News +Copyright (c) 2025 Y Combinator Hacker News Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index d2fa6a7..bf9fa67 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,17 @@ ## Overview -In partnership with [Firebase](https://www.firebase.com), we're making the public Hacker News data available in near real time. Firebase enables easy access from [Android](https://www.firebase.com/docs/android/), [iOS](https://www.firebase.com/docs/ios/) and the [web](https://www.firebase.com/docs/web/). Servers aren't left out; there's also [REST](https://www.firebase.com/docs/rest/) support. +In partnership with [Firebase](https://firebase.google.com/), we're making the public Hacker News data available in near real time. Firebase enables easy access from [Android](https://firebase.google.com/docs/android/setup), [iOS](https://firebase.google.com/docs/ios/setup) and the [web](https://firebase.google.com/docs/web/setup). [Servers](https://firebase.google.com/docs/server/setup) aren't left out. -If you can use one of the many [Firebase client libraries](https://www.firebase.com/docs/) you really should. The libraries handle networking efficiently and can raise events when things change. Be sure to check them out. +If you can use one of the many [Firebase client libraries](https://firebase.google.com/docs/libraries/), you really should. The libraries handle networking efficiently and can raise events when things change. Be sure to check them out. Please email api@ycombinator.com if you find any bugs. ## URI and Versioning -The API is based at https://hacker-news.firebaseio.com. +We hope to improve the API over time. The changes won't always be backward compatible, so we're going to use versioning. This first iteration will have URIs prefixed with `https://hacker-news.firebaseio.com/v0/` and is structured as described below. There is currently no rate limit. -We hope to improve it over time, and may later enable access to private per-user data using OAuth. The changes won't always be backward compatible, so we're going to version the API. This first iteration will live at https://hacker-news.firebaseio.com/v0/ and is structured as described below. +For versioning purposes, only removal of a non-optional field or alteration of an existing field will be considered incompatible changes. *Clients should gracefully handle additional fields they don't expect, and simply ignore them.* ## Design @@ -22,30 +22,31 @@ I'm not saying this to defend it - It's not the ideal public API, but it's the o ## Items -Stories, comments, jobs, Ask HNs and even polls are just items. They're identified by their ids, which are unique integers, and live under https://hacker-news.firebaseio.com/v0/item/. +Stories, comments, jobs, Ask HNs and even polls are just items. They're identified by their ids, which are unique integers, and live under `/v0/item/.json`. -All items have some of the following properties: +All items have some of the following properties, with required properties in bold: Field | Description ------|------------ -id | The item's unique id. Required. +**id** | The item's unique id. deleted | `true` if the item is deleted. type | The type of item. One of "job", "story", "comment", "poll", or "pollopt". by | The username of the item's author. time | Creation date of the item, in [Unix Time](http://en.wikipedia.org/wiki/Unix_time). text | The comment, story or poll text. HTML. dead | `true` if the item is dead. -parent | The item's parent. For comments, either another comment or the relevant story. For pollopts, the relevant poll. +parent | The comment's parent: either another comment or the relevant story. +poll | The pollopt's associated poll. kids | The ids of the item's comments, in ranked display order. url | The URL of the story. score | The story's score, or the votes for a pollopt. -title | The title of the story, poll or job. +title | The title of the story, poll or job. HTML. parts | A list of related pollopts, in display order. descendants | In the case of stories or polls, the total comment count. For example, a story: https://hacker-news.firebaseio.com/v0/item/8863.json?print=pretty -```json +```javascript { "by" : "dhouston", "descendants" : 71, @@ -61,7 +62,7 @@ For example, a story: https://hacker-news.firebaseio.com/v0/item/8863.json?print comment: https://hacker-news.firebaseio.com/v0/item/2921983.json?print=pretty -```json +```javascript { "by" : "norvig", "id" : 2921983, @@ -73,9 +74,40 @@ comment: https://hacker-news.firebaseio.com/v0/item/2921983.json?print=pretty } ``` +ask: https://hacker-news.firebaseio.com/v0/item/121003.json?print=pretty + +```javascript +{ + "by" : "tel", + "descendants" : 16, + "id" : 121003, + "kids" : [ 121016, 121109, 121168 ], + "score" : 25, + "text" : "or HN: the Next Iteration

I get the impression that with Arc being released a lot of people who never had time for HN before are suddenly dropping in more often. (PG: what are the numbers on this? I'm envisioning a spike.)

Not to say that isn't great, but I'm wary of Diggification. Between links comparing programming to sex and a flurry of gratuitous, ostentatious adjectives in the headlines it's a bit concerning.

80% of the stuff that makes the front page is still pretty awesome, but what's in place to keep the signal/noise ratio high? Does the HN model still work as the community scales? What's in store for (++ HN)?", + "time" : 1203647620, + "title" : "Ask HN: The Arc Effect", + "type" : "story" +} +``` + +job: https://hacker-news.firebaseio.com/v0/item/192327.json?print=pretty + +```javascript +{ + "by" : "justin", + "id" : 192327, + "score" : 6, + "text" : "Justin.tv is the biggest live video site online. We serve hundreds of thousands of video streams a day, and have supported up to 50k live concurrent viewers. Our site is growing every week, and we just added a 10 gbps line to our colo. Our unique visitors are up 900% since January.

There are a lot of pieces that fit together to make Justin.tv work: our video cluster, IRC server, our web app, and our monitoring and search services, to name a few. A lot of our website is dependent on Flash, and we're looking for talented Flash Engineers who know AS2 and AS3 very well who want to be leaders in the development of our Flash.

Responsibilities

    * Contribute to product design and implementation discussions\n    * Implement projects from the idea phase to production\n    * Test and iterate code before and after production release \n
\nQualifications

    * You should know AS2, AS3, and maybe a little be of Flex.\n    * Experience building web applications.\n    * A strong desire to work on website with passionate users and ideas for how to improve it.\n    * Experience hacking video streams, python, Twisted or rails all a plus.\n
\nWhile we're growing rapidly, Justin.tv is still a small, technology focused company, built by hackers for hackers. Seven of our ten person team are engineers or designers. We believe in rapid development, and push out new code releases every week. We're based in a beautiful office in the SOMA district of SF, one block from the caltrain station. If you want a fun job hacking on code that will touch a lot of people, JTV is for you.

Note: You must be physically present in SF to work for JTV. Completing the technical problem at http://www.justin.tv/problems/bml will go a long way with us. Cheers!", + "time" : 1210981217, + "title" : "Justin.tv is looking for a Lead Flash Engineer!", + "type" : "job", + "url" : "" +} +``` + poll: https://hacker-news.firebaseio.com/v0/item/126809.json?print=pretty -```json +```javascript { "by" : "pg", "descendants" : 54, @@ -92,11 +124,11 @@ poll: https://hacker-news.firebaseio.com/v0/item/126809.json?print=pretty and one of its parts: https://hacker-news.firebaseio.com/v0/item/160705.json?print=pretty -```json +```javascript { "by" : "pg", "id" : 160705, - "parent" : 160704, + "poll" : 160704, "score" : 335, "text" : "Yes, ban them; I'm tired of seeing Valleywag stories on News.YC.", "time" : 1207886576, @@ -106,24 +138,22 @@ and one of its parts: https://hacker-news.firebaseio.com/v0/item/160705.json?pri ## Users -Users are identified by case-sensitive ids, and live under https://hacker-news.firebaseio.com/v0/user/. +Users are identified by case-sensitive ids, and live under `/v0/user/`. Only users that have public activity (comments or story submissions) on the site are available through the API. Field | Description ------|------------ -id | The user's unique username. Case-sensitive. Required. -delay | Delay in minutes between a comment's creation and its visibility to other users. -created | Creation date of the user, in [Unix Time](http://en.wikipedia.org/wiki/Unix_time). -karma | The user's karma. +**id** | The user's unique username. Case-sensitive. Required. +**created** | Creation date of the user, in [Unix Time](http://en.wikipedia.org/wiki/Unix_time). +**karma** | The user's karma. about | The user's optional self-description. HTML. submitted | List of the user's stories, polls and comments. For example: https://hacker-news.firebaseio.com/v0/user/jl.json?print=pretty -```json +```javascript { "about" : "This is a test", "created" : 1173923446, - "delay" : 0, "id" : "jl", "karma" : 2937, "submitted" : [ 8265435, 8168423, 8090946, 8090326, 7699907, 7637962, 7596179, 7596163, 7594569, 7562135, 7562111, 7494708, 7494171, 7488093, 7444860, 7327817, 7280290, 7278694, 7097557, 7097546, 7097254, 7052857, 7039484, 6987273, 6649999, 6649706, 6629560, 6609127, 6327951, 6225810, 6111999, 5580079, 5112008, 4907948, 4901821, 4700469, 4678919, 3779193, 3711380, 3701405, 3627981, 3473004, 3473000, 3457006, 3422158, 3136701, 2943046, 2794646, 2482737, 2425640, 2411925, 2408077, 2407992, 2407940, 2278689, 2220295, 2144918, 2144852, 1875323, 1875295, 1857397, 1839737, 1809010, 1788048, 1780681, 1721745, 1676227, 1654023, 1651449, 1641019, 1631985, 1618759, 1522978, 1499641, 1441290, 1440993, 1436440, 1430510, 1430208, 1385525, 1384917, 1370453, 1346118, 1309968, 1305415, 1305037, 1276771, 1270981, 1233287, 1211456, 1210688, 1210682, 1194189, 1193914, 1191653, 1190766, 1190319, 1189925, 1188455, 1188177, 1185884, 1165649, 1164314, 1160048, 1159156, 1158865, 1150900, 1115326, 933897, 924482, 923918, 922804, 922280, 922168, 920332, 919803, 917871, 912867, 910426, 902506, 891171, 807902, 806254, 796618, 786286, 764412, 764325, 642566, 642564, 587821, 575744, 547504, 532055, 521067, 492164, 491979, 383935, 383933, 383930, 383927, 375462, 263479, 258389, 250751, 245140, 243472, 237445, 229393, 226797, 225536, 225483, 225426, 221084, 213940, 213342, 211238, 210099, 210007, 209913, 209908, 209904, 209903, 170904, 165850, 161566, 158388, 158305, 158294, 156235, 151097, 148566, 146948, 136968, 134656, 133455, 129765, 126740, 122101, 122100, 120867, 120492, 115999, 114492, 114304, 111730, 110980, 110451, 108420, 107165, 105150, 104735, 103188, 103187, 99902, 99282, 99122, 98972, 98417, 98416, 98231, 96007, 96005, 95623, 95487, 95475, 95471, 95467, 95326, 95322, 94952, 94681, 94679, 94678, 94420, 94419, 94393, 94149, 94008, 93490, 93489, 92944, 92247, 91713, 90162, 90091, 89844, 89678, 89498, 86953, 86109, 85244, 85195, 85194, 85193, 85192, 84955, 84629, 83902, 82918, 76393, 68677, 61565, 60542, 47745, 47744, 41098, 39153, 38678, 37741, 33469, 12897, 6746, 5252, 4752, 4586, 4289 ] @@ -136,41 +166,41 @@ The coolest part of Firebase is its support for change notifications. While you ### Max Item ID -The current largest item id is at https://hacker-news.firebaseio.com/v0/maxitem. You can walk backward from here to discover all items. +The current largest item id is at `/v0/maxitem`. You can walk backward from here to discover all items. Example: https://hacker-news.firebaseio.com/v0/maxitem.json?print=pretty -```json +```javascript 9130260 ``` -### New and Top Stories +### New, Top and Best Stories -Up to 500 top and new stories are at https://hacker-news.firebaseio.com/v0/topstories and https://hacker-news.firebaseio.com/v0/newstories. +Up to 500 top and new stories are at `/v0/topstories` (also contains jobs) and `/v0/newstories`. Best stories are at `/v0/beststories`. Example: https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty -```json +```javascript [ 9129911, 9129199, 9127761, 9128141, 9128264, 9127792, 9129248, 9127092, 9128367, ..., 9038733 ] ``` ### Ask, Show and Job Stories -Up to 200 of the latest Ask HN, Show HN, and Job stories are at https://hacker-news.firebaseio.com/v0/askstories, https://hacker-news.firebaseio.com/v0/showstories, and https://hacker-news.firebaseio.com/v0/jobstories. +Up to 200 of the latest Ask HN, Show HN, and Job stories are at `/v0/askstories`, `/v0/showstories`, and `/v0/jobstories`. Example: https://hacker-news.firebaseio.com/v0/askstories.json?print=pretty -```json +```javascript [ 9127232, 9128437, 9130049, 9130144, 9130064, 9130028, 9129409, 9127243, 9128571, ..., 9120990 ] ``` ### Changed Items and Profiles -The item and profile changes are at https://hacker-news.firebaseio.com/v0/updates. +The item and profile changes are at `/v0/updates`. Example: https://hacker-news.firebaseio.com/v0/updates.json?print=pretty -```json +```javascript { "items" : [ 8423305, 8420805, 8423379, 8422504, 8423178, 8423336, 8422717, 8417484, 8423378, 8423238, 8423353, 8422395, 8423072, 8423044, 8423344, 8423374, 8423015, 8422428, 8423377, 8420444, 8423300, 8422633, 8422599, 8422408, 8422928, 8394339, 8421900, 8420902, 8422087 ], "profiles" : [ "thefox", "mdda", "plinkplonk", "GBond", "rqebmm", "neom", "arram", "mcmancini", "metachris", "DubiousPusher", "dochtman", "kstrauser", "biren34", "foobarqux", "mkehrt", "nathanm412", "wmblaettler", "JoeAnzalone", "rcconf", "johndbritton", "msie", "cktsai", "27182818284", "kevinskii", "wildwood", "mcherm", "naiyt", "matthewmcg", "joelhaus", "tshtf", "MrZongle2", "Bogdanp" ]