From 5b1ead332c90f7dd60bd5829762dedc7fb583e44 Mon Sep 17 00:00:00 2001 From: Zach Munro-Cape Date: Thu, 19 Mar 2015 21:42:31 -0300 Subject: [PATCH 01/35] Explicitly include a job type response Was working on a Go client implementation and noticed that a Job example was not provided. --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index d2fa6a7..d86dcb8 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,20 @@ comment: https://hacker-news.firebaseio.com/v0/item/2921983.json?print=pretty } ``` +job: https://hacker-news.firebaseio.com/v0/item/9235551.json?print=pretty +```json +{ + "by" : "nickporter", + "id" : 9235551, + "score" : 1, + "text" : "We change the way brick-and-mortar retailers interact with their data. We help them make better decisions and grow their business.

The landscape is currently dominated by legacy software from SAP, Oracle, IBM, etc. We're showing our customers what beautifully crafted software looks like.

We're looking for driven individuals to help architect and implement the next iteration of our platform. Our customers include multinational retailers from across the world, so you'll get a chance to learn the inside operations of some of the biggest consumer-facing companies. Oh and we're processing over 1 billion dollars worth of transactional data.

The ideal candidate can easily work in 2 of these areas of the stack:

    - UI/UX Design\n    - Frontend       (Angular, D3, CoffeeScript, SASS, Jade, Grunt)\n    - Backend        (Node, Python, Go, SQL)\n    - Infrastructure (Spark, Docker, CoreOS, Kubernetes, AWS)\n
\nWe are constantly improving and evolving our stack, so it's not a big deal if you don't know some of the tech that's listed. What's important is that you have a passion for your craft and that you're able to learn quickly. Our team is growing, so this is an awesome opportunity to be part of the core product and engineering team and lay the foundation of the platform.

What we offer:

    - A fully stocked fridge\n    - An office in SOMA, San Francisco, 10min away from Bart or Caltrain\n    - Paid lunches\n    - Flexible vacation time\n    - Full healthcare package\n    - Generous stock option plan\n    - Whatever gear you need\n    - Visa sponsorships\n
\nSend an email to `nick@42technologies.com` if you're interested!", + "time" : 1426811086, + "title" : "42 (YC W14) is hiring engineers to help fix retail", + "type" : "job", + "url" : "" +} +``` + poll: https://hacker-news.firebaseio.com/v0/item/126809.json?print=pretty ```json From 61014e966a36fccd31787f3d5db9f79ef1d8a91c Mon Sep 17 00:00:00 2001 From: Nick Sivo Date: Sun, 12 Apr 2015 13:47:31 -0700 Subject: [PATCH 02/35] Warn about additional fields in same API version. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index d2fa6a7..ac0e359 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ The API is based at https://hacker-news.firebaseio.com. 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 The v0 API is essentially a dump of our in-memory data structures. We know, what works great locally in memory isn't so hot over the network. Many of the awkward things are just the way HN works internally. Want to know the total number of comments on an article? Traverse the tree and count. Want to know the children of an item? Load the item and get their IDs, then load them. The newest page? Starts at item maxid and walks backward, keeping only the top level stories. Same for Ask, Show, etc. From 52a09491451991520a5cd0d9b3a29f539cade8dd Mon Sep 17 00:00:00 2001 From: Nick Sivo Date: Sun, 12 Apr 2015 14:04:24 -0700 Subject: [PATCH 03/35] Update README.md --- README.md | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f84b602..80e484a 100644 --- a/README.md +++ b/README.md @@ -75,15 +75,33 @@ comment: https://hacker-news.firebaseio.com/v0/item/2921983.json?print=pretty } ``` -job: https://hacker-news.firebaseio.com/v0/item/9235551.json?print=pretty +ask: https://hacker-news.firebaseio.com/v0/item/121003.json?print=pretty + +```json +{ + "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", + "url" : "" +} +``` + +job: https://hacker-news.firebaseio.com/v0/item/192327.json?print=pretty + ```json { - "by" : "nickporter", - "id" : 9235551, - "score" : 1, - "text" : "We change the way brick-and-mortar retailers interact with their data. We help them make better decisions and grow their business.

The landscape is currently dominated by legacy software from SAP, Oracle, IBM, etc. We're showing our customers what beautifully crafted software looks like.

We're looking for driven individuals to help architect and implement the next iteration of our platform. Our customers include multinational retailers from across the world, so you'll get a chance to learn the inside operations of some of the biggest consumer-facing companies. Oh and we're processing over 1 billion dollars worth of transactional data.

The ideal candidate can easily work in 2 of these areas of the stack:

    - UI/UX Design\n    - Frontend       (Angular, D3, CoffeeScript, SASS, Jade, Grunt)\n    - Backend        (Node, Python, Go, SQL)\n    - Infrastructure (Spark, Docker, CoreOS, Kubernetes, AWS)\n
\nWe are constantly improving and evolving our stack, so it's not a big deal if you don't know some of the tech that's listed. What's important is that you have a passion for your craft and that you're able to learn quickly. Our team is growing, so this is an awesome opportunity to be part of the core product and engineering team and lay the foundation of the platform.

What we offer:

    - A fully stocked fridge\n    - An office in SOMA, San Francisco, 10min away from Bart or Caltrain\n    - Paid lunches\n    - Flexible vacation time\n    - Full healthcare package\n    - Generous stock option plan\n    - Whatever gear you need\n    - Visa sponsorships\n
\nSend an email to `nick@42technologies.com` if you're interested!", - "time" : 1426811086, - "title" : "42 (YC W14) is hiring engineers to help fix retail", + "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" : "" } From 042a802ec50f7ceb6515ae69a442d00cc1033b8a Mon Sep 17 00:00:00 2001 From: Nick Sivo Date: Sun, 12 Apr 2015 14:08:56 -0700 Subject: [PATCH 04/35] Formatting tweaks. --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 80e484a..950efec 100644 --- a/README.md +++ b/README.md @@ -26,14 +26,14 @@ I'm not saying this to defend it - It's not the ideal public API, but it's the o 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/. -All items have some of the following properties: +All items have some of the following properties, with require 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. +**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. @@ -144,10 +144,10 @@ Users are identified by case-sensitive ids, and live under https://hacker-news.f Field | Description ------|------------ -id | The user's unique username. Case-sensitive. Required. +**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. +**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. From 22d55f0966714fab0333390667605a73196e707c Mon Sep 17 00:00:00 2001 From: Nick Sivo Date: Sun, 26 Apr 2015 18:30:34 -0700 Subject: [PATCH 05/35] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 950efec..50774c4 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Field | Description **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. +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. From f6467837b40a0505956865ddc49f4ba7171f57af Mon Sep 17 00:00:00 2001 From: bjc Date: Sun, 7 Jun 2015 15:04:37 -0400 Subject: [PATCH 06/35] typo fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 50774c4..fcf8ce6 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ I'm not saying this to defend it - It's not the ideal public API, but it's the o 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/. -All items have some of the following properties, with require properties in bold: +All items have some of the following properties, with required properties in bold: Field | Description ------|------------ From 7d149e34862608256374591b84c11cbb0a07df25 Mon Sep 17 00:00:00 2001 From: Scott Bell Date: Thu, 18 Jun 2015 10:20:15 -0700 Subject: [PATCH 07/35] Clarify user profile availability --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fcf8ce6..b3ccbfc 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,7 @@ 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 https://hacker-news.firebaseio.com/v0/user/. Only users that have public activity (comments or story submissions) on the site are available through the API. Field | Description ------|------------ From 274dc7003165012a0df0b553146c84652a5c53cd Mon Sep 17 00:00:00 2001 From: Scott Bell Date: Sat, 23 Apr 2016 12:06:42 -0700 Subject: [PATCH 08/35] Minor README update --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b3ccbfc..2987ec0 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Please email api@ycombinator.com if you find any bugs. ## URI and Versioning -The API is based at https://hacker-news.firebaseio.com. +The current API is based at https://hacker-news.firebaseio.com/v0/. 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. From 831ca52999b4ac9b0b27a60fcd4e80e5bff341a7 Mon Sep 17 00:00:00 2001 From: Scott Bell Date: Sat, 23 Apr 2016 14:01:15 -0700 Subject: [PATCH 09/35] More small README changes --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 2987ec0..c962b4d 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,7 @@ Please email api@ycombinator.com if you find any bugs. ## URI and Versioning -The current API is based at https://hacker-news.firebaseio.com/v0/. - -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. +We hope to improve the API 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 use versioning. This first iteration will have URIs prefixed with 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.* From c7222376bf438d6f140d417d8473263912dd67bb Mon Sep 17 00:00:00 2001 From: Alexander Pepper Date: Tue, 17 May 2016 19:49:52 +0200 Subject: [PATCH 10/35] Added "beststories". API endpoint for https://news.ycombinator.com/best --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c962b4d..5221a4c 100644 --- a/README.md +++ b/README.md @@ -176,9 +176,9 @@ Example: https://hacker-news.firebaseio.com/v0/maxitem.json?print=pretty 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 https://hacker-news.firebaseio.com/v0/topstories and https://hacker-news.firebaseio.com/v0/newstories. Best stories are at https://hacker-news.firebaseio.com/v0/beststories. Example: https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty From 83fb444e7a5673ef234b3c9d04c47aac9fe2fe3d Mon Sep 17 00:00:00 2001 From: kelukelu Date: Thu, 7 Jul 2016 17:52:53 -0700 Subject: [PATCH 11/35] Links are deprecated. Change to new ones. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5221a4c..99b4dd8 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ ## 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. From 645a8b8eec7d116fc28d8049923c7d9faa833996 Mon Sep 17 00:00:00 2001 From: kelukelu Date: Sat, 9 Jul 2016 10:52:57 -0700 Subject: [PATCH 12/35] Add comment on rate limit I read the original post and saw others had asked before. People might wonder in the future too. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 99b4dd8..4c1dd84 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Please email api@ycombinator.com if you find any bugs. ## URI and Versioning -We hope to improve the API 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 use versioning. This first iteration will have URIs prefixed with https://hacker-news.firebaseio.com/v0/ and is structured as described below. +We hope to improve the API 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 use versioning. This first iteration will have URIs prefixed with https://hacker-news.firebaseio.com/v0/ and is structured as described below. There is no rate limit. 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.* From 249798569ea0e0868d93ed14b8e13509c4453199 Mon Sep 17 00:00:00 2001 From: Scott Bell Date: Sat, 9 Jul 2016 11:08:51 -0700 Subject: [PATCH 13/35] Minor rate limit tweak --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4c1dd84..a2ef483 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Please email api@ycombinator.com if you find any bugs. ## URI and Versioning -We hope to improve the API 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 use versioning. This first iteration will have URIs prefixed with https://hacker-news.firebaseio.com/v0/ and is structured as described below. There is no rate limit. +We hope to improve the API 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 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. 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.* From e4849ac4adc4f9665345ea641456e2e763a3cab7 Mon Sep 17 00:00:00 2001 From: r3c0d3x Date: Sun, 6 Nov 2016 14:35:09 -0500 Subject: [PATCH 14/35] Fix syntax highlighting for various examples --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index a2ef483..7825a8a 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ 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 +61,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, @@ -75,7 +75,7 @@ comment: https://hacker-news.firebaseio.com/v0/item/2921983.json?print=pretty ask: https://hacker-news.firebaseio.com/v0/item/121003.json?print=pretty -```json +```javascript { "by" : "tel", "descendants" : 16, @@ -92,7 +92,7 @@ ask: https://hacker-news.firebaseio.com/v0/item/121003.json?print=pretty job: https://hacker-news.firebaseio.com/v0/item/192327.json?print=pretty -```json +```javascript { "by" : "justin", "id" : 192327, @@ -107,7 +107,7 @@ job: https://hacker-news.firebaseio.com/v0/item/192327.json?print=pretty poll: https://hacker-news.firebaseio.com/v0/item/126809.json?print=pretty -```json +```javascript { "by" : "pg", "descendants" : 54, @@ -124,7 +124,7 @@ 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, @@ -151,7 +151,7 @@ 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, @@ -172,7 +172,7 @@ The current largest item id is at https://hacker-news.firebaseio.com/v0/maxitem. Example: https://hacker-news.firebaseio.com/v0/maxitem.json?print=pretty -```json +```javascript 9130260 ``` @@ -182,7 +182,7 @@ Up to 500 top and new stories are at https://hacker-news.firebaseio.com/v0/topst Example: https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty -```json +```javascript [ 9129911, 9129199, 9127761, 9128141, 9128264, 9127792, 9129248, 9127092, 9128367, ..., 9038733 ] ``` @@ -192,7 +192,7 @@ Up to 200 of the latest Ask HN, Show HN, and Job stories are at https://hacker-n Example: https://hacker-news.firebaseio.com/v0/askstories.json?print=pretty -```json +```javascript [ 9127232, 9128437, 9130049, 9130144, 9130064, 9130028, 9129409, 9127243, 9128571, ..., 9120990 ] ``` @@ -202,7 +202,7 @@ The item and profile changes are at https://hacker-news.firebaseio.com/v0/update 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" ] From 1688262ab6e899e94831e59102d25de0a2a425df Mon Sep 17 00:00:00 2001 From: Scott Bell Date: Fri, 21 Apr 2017 16:07:21 -0700 Subject: [PATCH 15/35] Update property description for pollopts The parent property on pollopts was superseded by poll in May 2016. Thanks to Jacek Ciolek for reporting. --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7825a8a..4a7c5a8 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,8 @@ 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. @@ -128,7 +129,7 @@ and one of its parts: https://hacker-news.firebaseio.com/v0/item/160705.json?pri { "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, From bbba32e6a18ca61b8067fcc39b7051827dd86bd8 Mon Sep 17 00:00:00 2001 From: Scott Bell Date: Fri, 23 Jun 2017 10:22:59 -0700 Subject: [PATCH 16/35] Remove links for invalid URIs --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4a7c5a8..6a14621 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Please email api@ycombinator.com if you find any bugs. ## URI and Versioning -We hope to improve the API 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 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 the API 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 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. 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.* @@ -22,7 +22,7 @@ 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/`. All items have some of the following properties, with required properties in bold: @@ -139,7 +139,7 @@ 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/. Only users that have public activity (comments or story submissions) on the site are available through the API. +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 ------|------------ @@ -169,7 +169,7 @@ 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 @@ -179,7 +179,7 @@ Example: https://hacker-news.firebaseio.com/v0/maxitem.json?print=pretty ### 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. Best stories are at https://hacker-news.firebaseio.com/v0/beststories. +Up to 500 top and new stories are at `/v0/topstories` and `/v0/newstories`. Best stories are at `/v0/beststories`. Example: https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty @@ -189,7 +189,7 @@ Example: https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty ### 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 @@ -199,7 +199,7 @@ Example: https://hacker-news.firebaseio.com/v0/askstories.json?print=pretty ### 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 From c427ad63e9efcead0faa75ac1137112a574a45b9 Mon Sep 17 00:00:00 2001 From: Aaron Meese Date: Thu, 26 Oct 2017 20:32:03 -0500 Subject: [PATCH 17/35] Update README.md Added proper comma --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6a14621..4ea9c07 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ 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://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. +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. From e8c76d0b91cba6e351ceef03d0807b6d501b6ccf Mon Sep 17 00:00:00 2001 From: Shawn Presser Date: Thu, 25 Jan 2018 17:48:27 -0600 Subject: [PATCH 18/35] Update copyright year --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 2823c8e..d9af16b 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2014 Y Combinator Hacker News +Copyright (c) 2018 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 From 99c6c6130357396a2b5026baaf7328b3a8820e0a Mon Sep 17 00:00:00 2001 From: Scott Bell Date: Thu, 30 Aug 2018 09:35:53 -0700 Subject: [PATCH 19/35] Minor README update --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4ea9c07..fdcdbb3 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Please email api@ycombinator.com if you find any bugs. ## URI and Versioning -We hope to improve the API 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 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 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. 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.* From a7a69fb817dc0d6e13be09b377f53caa48610fca Mon Sep 17 00:00:00 2001 From: Edward Betts Date: Sun, 27 Jan 2019 15:26:51 +0000 Subject: [PATCH 20/35] Update copyright year --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index d9af16b..7ec0fa1 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2018 Y Combinator Hacker News +Copyright (c) 2019 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 From 96f2fa27501faeb0d09a82088d729987aa2ba01b Mon Sep 17 00:00:00 2001 From: Louis Tsai Date: Sun, 14 Jul 2019 17:58:27 +0200 Subject: [PATCH 21/35] Specify both story and job can be return from topstories --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index fdcdbb3..f3b8cc5 100644 --- a/README.md +++ b/README.md @@ -181,6 +181,12 @@ Example: https://hacker-news.firebaseio.com/v0/maxitem.json?print=pretty Up to 500 top and new stories are at `/v0/topstories` and `/v0/newstories`. Best stories are at `/v0/beststories`. +| | `topstories` | `newstories` | `beststories` | +|---------|--------------|--------------|---------------| +| `story` | ✔ | ✔ | ✔ | +| `job` | ✔ | | | + + Example: https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty ```javascript From 4611770d14ff151d2bfa2aa3ccfab7c4243deb1f Mon Sep 17 00:00:00 2001 From: Scott Bell Date: Sun, 14 Jul 2019 09:11:03 -0700 Subject: [PATCH 22/35] Minor update to description of story lists This is less crisp than the previous table but is probably sufficient. --- README.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/README.md b/README.md index f3b8cc5..10c4937 100644 --- a/README.md +++ b/README.md @@ -179,13 +179,7 @@ Example: https://hacker-news.firebaseio.com/v0/maxitem.json?print=pretty ### New, Top and Best Stories -Up to 500 top and new stories are at `/v0/topstories` and `/v0/newstories`. Best stories are at `/v0/beststories`. - -| | `topstories` | `newstories` | `beststories` | -|---------|--------------|--------------|---------------| -| `story` | ✔ | ✔ | ✔ | -| `job` | ✔ | | | - +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 From 5e5bc8d96f30f28caa4e24c0512a12bcd86fd1fc Mon Sep 17 00:00:00 2001 From: troyengel Date: Wed, 18 Dec 2019 10:01:38 -0600 Subject: [PATCH 23/35] clarify title may use HTML encoded entities --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10c4937..88ddfa5 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ 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. From 923a4d6940ec3b38145ad45a1ccab6aa3936cd4f Mon Sep 17 00:00:00 2001 From: Ross Waycaster Date: Mon, 2 Mar 2020 12:14:50 -0600 Subject: [PATCH 24/35] Update copywrite year --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 7ec0fa1..9f630e4 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2019 Y Combinator Hacker News +Copyright (c) 2020 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 From 11512258c3109f38a4104bbba6e0a32e3e29b056 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antti=20M=C3=A4ki?= Date: Thu, 23 Apr 2020 11:13:03 +0300 Subject: [PATCH 25/35] Remove url from "Ask HN" responses The response currently doesn't include url attribute, so the documentation was misleading. --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 88ddfa5..d9194d7 100644 --- a/README.md +++ b/README.md @@ -86,8 +86,7 @@ ask: https://hacker-news.firebaseio.com/v0/item/121003.json?print=pretty "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", - "url" : "" + "type" : "story" } ``` From 15b2c89bcef6a38048770fb04adfdbd5aca5d374 Mon Sep 17 00:00:00 2001 From: Daniel Gackle Date: Wed, 16 Dec 2020 10:24:05 -0800 Subject: [PATCH 26/35] Removed 'delay' from list of user fields. It isn't published. --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index d9194d7..c300667 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,6 @@ Users are identified by case-sensitive ids, and live under `/v0/user/`. Only use 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. about | The user's optional self-description. HTML. From da1228470fe8c50aee674578e00e309692179070 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=87a=C4=9Fr=C4=B1=20=C3=96zkan?= Date: Mon, 22 Mar 2021 00:42:19 +0300 Subject: [PATCH 27/35] Update copyright year --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 9f630e4..3bd7d85 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2020 Y Combinator Hacker News +Copyright (c) 2021 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 From e831304014276eef69651cf1a4625cb4f8396863 Mon Sep 17 00:00:00 2001 From: trollmao <88042940+trollmao@users.noreply.github.com> Date: Sat, 1 Jan 2022 13:51:14 -0600 Subject: [PATCH 28/35] Update LICENSE --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 3bd7d85..f14cddf 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2021 Y Combinator Hacker News +Copyright (c) 2022 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 From 1884e6258edbc6577c2d6750b4db394b113ad8d9 Mon Sep 17 00:00:00 2001 From: StoddLabs <117788465+StoddLabs@users.noreply.github.com> Date: Sat, 14 Jan 2023 00:28:47 -0600 Subject: [PATCH 29/35] updated copyright date --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index f14cddf..9411b3d 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2022 Y Combinator Hacker News +Copyright (c) 2023 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 From 6a3870d31efe3a7b585be0df44c67b2e598da0d6 Mon Sep 17 00:00:00 2001 From: William Kaiser Date: Mon, 21 Aug 2023 20:27:09 -0400 Subject: [PATCH 30/35] Added .json to path for valid url Only putting the trailing object id leads to errors --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c300667..aa703d1 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ 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 `/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, with required properties in bold: From 951a407bf6aef7f6c1906f2bb54bb58f532da108 Mon Sep 17 00:00:00 2001 From: presbrey Date: Mon, 3 Jun 2024 23:56:28 -0400 Subject: [PATCH 31/35] Bump year in LICENSE Just following the last HEAD~3 tradition of sending in this PR :) Thanks for continuing to provide this API to the public! --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 9411b3d..6be5a2f 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2023 Y Combinator Hacker News +Copyright (c) 2024 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 From d4301c0ce094ae0fc62aad9bc886a72f563e9318 Mon Sep 17 00:00:00 2001 From: Yves Dorfsman Date: Thu, 6 Jun 2024 08:24:46 -0600 Subject: [PATCH 32/35] Remove delay from Users example --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index c300667..facae68 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,6 @@ For example: https://hacker-news.firebaseio.com/v0/user/jl.json?print=pretty { "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 ] From 4f4d21ce68da8da8f456d6ad923b21f69224861a Mon Sep 17 00:00:00 2001 From: MUJJONA ERIC <130629472+EricMujjona@users.noreply.github.com> Date: Sun, 29 Sep 2024 04:29:42 +0300 Subject: [PATCH 33/35] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index facae68..177df86 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Hacker News API +# Hacker News API // ## Overview From 44488c761da600b34191a771eda31befb8ed9c2a Mon Sep 17 00:00:00 2001 From: gruseom Date: Sat, 28 Sep 2024 18:57:28 -0700 Subject: [PATCH 34/35] Revert "Update README.md" --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 177df86..facae68 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Hacker News API // +# Hacker News API ## Overview From 1fff41df2527fb24ece748acb928fa0cd6db048a Mon Sep 17 00:00:00 2001 From: JasonnnW3000 Date: Wed, 1 Jan 2025 00:07:46 -0500 Subject: [PATCH 35/35] Update LICENSE, fix license year Signed-off-by: JasonnnW3000 --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 6be5a2f..c565a55 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2024 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