api.md

HNPWA API

A fast, CDN delivered, aggregated Hacker News API

https://api.hnpwa.com/v0/news/1.json

Why?

Everything in the official Hacker News API is either an item or a list of items.

This structure is not ideal for building fast loading Progressive Web Apps since it will require multiple network requests to get the needed payload for page render.

The HNPWA solves this problem by aggregating each item in the id list into item feeds.

Item feeds

There are five item feeds.

Name	URL
News	https://api.hnpwa.com/v0/news/1.json
Newest	https://api.hnpwa.com/v0/newest/1.json
Ask	https://api.hnpwa.com/v0/ask/1.json
Show	https://api.hnpwa.com/v0/show/1.json
Jobs	https://api.hnpwa.com/v0/jobs/1.json

Schema

Each item feed returns an array of FeedItem.

export interface FeedItem {
  id: number;
  title: string;
  points?: number | null;
  user?: string | null;
  time: number;
  time_ago: string;
  comments_count: number;
  type: string;
  url?: string;
  domain?: string;
}

Paging

Item feeds can be paged by accessing the next index in the page. Each page starts at 1 and each feed has a different ending page.

https://api.hnpwa.com/v0/news.json/2.json

Name	Max Pages
News	10
Newest	12
Ask	2
Show	2
Jobs	1

Individual items

Feeds provide the top level view of an item, but other details like comment threads are available at the individual item level.

https://api.hnpwa.com/v0/item/13831370.json

Schema

export interface Item {
  id: number;
  title: string;
  points: number | null;
  user: string | null;
  time: number;
  time_ago: string;
  content: string;
  deleted?: boolean;
  dead?: boolean;
  type: string;
  url?: string;
  domain?: string;
  comments: Item[]; // Comments are items too
  level: number;
  comments_count: number;
}

Users

Users are retrieved by username.

https://api.hnpwa.com/v0/user/davideast.json

Schema

export interface User {
  about?: string;
  created_time: number;
  created: string;
  id: string;
  karma: number;  
}

Local Development

The HNPWA API uses the hnpwa-api module and runs on Cloud Functions and Firebase Hosting. If you want to run the API while offline you can globally install the module to serve offline.

npm i -g hnpwa-api
hnpwa-api --save # saves current HN API data set offline
hnpwa-api --serve --offline --port=4000