restructure docs 📝, status badge

api.js

@@ -59,7 +59,7 @@ const config = {
 	logging: true,
 	aboutPage: false,
 	etags: 'strong',
-	csp: `default-src 'none' style-src 'self' 'unsafe-inline'`,
+	csp: `default-src 'none' style-src 'self' 'unsafe-inline' img-src https:`,
 	healthCheck,
 	modifyRoutes,
 }

docs/readme.md

@@ -1,9 +1,28 @@
 # `v5.db.transport.rest` documentation
 
-[`v5.db.transport.rest`](https://v5.db.transport.rest/) is a [REST API](https://restfulapi.net).
+[`v5.db.transport.rest`](https://v5.db.transport.rest/) is a [REST API](https://restfulapi.net) for the public transportation system in Germany.
 
-You can just use the API without authentication. In the future, we may [rate-limit](https://apisyouwonthate.com/blog/what-is-api-rate-limiting-all-about) your IP address if you make too many requests.
+[![API status](https://badgen.net/uptime-robot/status/m784879516-8a977fa91b975fc3884a9857)](https://stats.uptimerobot.com/57wNLs39M/784879516)
+
+Because it wraps [an API](https://github.com/public-transport/hafas-client/blob/master/readme.md#background) of [Deutsche Bahn](https://de.wikipedia.org/wiki/Deutsche_Bahn), it **includes most of the long-distance and regional traffic, as well as some international trains and local buses**. Essentially, it returns whatever data the [*DB Navigator* app](https://www.bahn.de/p/view/service/mobile/db-navigator.shtml) shows, **including realtime delays and disruptions**.
 
 - [Getting Started](getting-started.md)
 - [API documentation](api.md)
-- [Why this API?](why.md)
+
+## Why use this API?
+
+### Realtime Data
+
+This API returns realtime data whenever its upstream, the [API for DB's mobile app](https://github.com/public-transport/hafas-client/blob/33d7d30acf235c54887c6459a15fe581982c6a19/p/db/readme.md), provides it.
+
+### No API Key
+
+You can just use the API without authentication. There's a [rate limit](https://apisyouwonthate.com/blog/what-is-api-rate-limiting-all-about) of 100 requests/minute (burst 200 requests/minute) set up.
+
+### CORS
+
+This API has [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) enabled, so you can query it from any webpage.
+
+### Caching-friendly
+
+This API sends [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) & [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers, allowing clients cache responses properly.

docs/why.md

@@ -1,104 +0,0 @@
-# Why use this API?
-
-[Deutsche Bahn itself provides an API.](https://data.deutschebahn.com/dataset/api-fahrplan) Why use this one? (And what could DB do better?)
-
-## Realtime Data
-
-This API returns realtime data whenever its upstream, the [API for DB's mobile app](https://github.com/public-transport/hafas-client/blob/e02a20b1de59bda3cd380445b6105e4c46036636/p/db/readme.md), provides it.
-
-## No API Key
-
-Especially on web sites/apps, it is a subpar solution to the send API keys to the client. Also, you have to obtain these keys manually and cannot automatically revoke them. **This API doesn't require a key.**
-
-## CORS
-
-If you want to use transport information on a web site/app, [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) must be enabled. Otherwise, you would have to send all requests through your own proxy server. **This API has CORS enabled.**
-
-## Readable Markup
-
-Compare the underlying HAFAS API:
-
-```js
-{
-	cid: 'C-0',
-	date: '20171216',
-	sDays: { /* … */ },
-	dep: {
-		locX: 0,
-		dPlatfS: '6',
-		dInR: true,
-		dTimeS: '115400',
-		dProgType: 'PROGNOSED',
-		dTZOffset: 60,
-		type: 'N'
-	},
-	arr: {
-		locX: 2,
-		aPlatfS: '4',
-		aOutR: true,
-		aTimeS: '162600',
-		aProgType: 'PROGNOSED',
-		aTZOffset: 60,
-		type: 'N'
-	},
-	/* … */
-}
-```
-
-to this one:
-
-```js
-{
-	origin: {
-		type: 'station',
-		id: '8089066',
-		name: 'Berlin Friedrichstraße (S)',
-		location: {
-			type: 'location',
-			latitude: 52.520331,
-			longitude: 13.386934
-		},
-		products: {
-			nationalExp: false,
-			national: false,
-			regionalExp: false,
-			regional: true,
-			suburban: true,
-			bus: true,
-			ferry: false,
-			subway: true,
-			tram: true,
-			taxi: false
-		},
-	},
-	destination: {
-		type: 'station',
-		id: '8004158',
-		name: 'München-Pasing',
-		location: {
-			type: 'location',
-			latitude: 48.150036,
-			longitude: 11.461624
-		},
-		products: { /* … */ },
-	},
-	departure: '2017-12-16T11:54:00.000+01:00',
-	arrival: '2017-12-16T16:26:00.000+01:00',
-}
-```
-
-## Caching-friendly
-
-This API sends [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) & [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers, allowing clients to refresh their state efficiently.
-
-## HTTP/2
-
-[HTTP/2](https://http2.github.io/) allows multiple requests at a time, efficiently pipelines sequential requests and compresses headers. See [Cloudflare's HTTP/2 page](https://blog.cloudflare.com/http-2-for-web-developers/).
-
-## Proper HTTP, Proper REST
-
-This wrapper API follows [REST-ful design principles](https://restfulapi.net), it uses `GET`, and proper paths & headers.
-
-## Monitoring
-
-There's a [status board](https://status.transport.rest) that shows realtime uptime statistics.

package.json

@@ -39,7 +39,7 @@
 		"pino-pretty": "^4.0.0"
 	},
 	"scripts": {
-		"docs": "node api-docs.js >docs/api.md && build-technical-doc --syntax-stylesheet-url /syntax.css <docs/readme.md >docs/index.html && build-technical-doc --syntax-stylesheet-url /syntax.css <docs/getting-started.md >docs/getting-started.html && build-technical-doc --syntax-stylesheet-url /syntax.css <docs/why.md >docs/why.html && build-technical-doc --syntax-stylesheet-url /syntax.css <docs/api.md >docs/api.html && build-technical-doc --syntax-stylesheet github >docs/syntax.css",
+		"docs": "node api-docs.js >docs/api.md && build-technical-doc --syntax-stylesheet-url /syntax.css <docs/readme.md >docs/index.html && build-technical-doc --syntax-stylesheet-url /syntax.css <docs/getting-started.md >docs/getting-started.html && build-technical-doc --syntax-stylesheet-url /syntax.css <docs/api.md >docs/api.html && build-technical-doc --syntax-stylesheet github >docs/syntax.css",
 		"build": "npm run docs",
 		"start": "node index.js"
 	}

readme.md

@@ -2,10 +2,11 @@
 
 **A clean REST API wrapping around the [Deutsche Bahn HAFAS API](https://github.com/public-transport/db-hafas#db-hafas).** It is deployed at [`v5.db.transport.rest`](https://v5.db.transport.rest/).
 
-[API Documentation](docs/index.md) | [Why?](docs/why.md)
+[**API Documentation**](docs/index.md)
 
 ![db-rest architecture diagram](architecture.svg)
 
+[![API status](https://badgen.net/uptime-robot/status/m784879516-8a977fa91b975fc3884a9857)](https://stats.uptimerobot.com/57wNLs39M/784879516)
 [![Docker build status](https://img.shields.io/docker/build/derhuerst/db-rest.svg)](https://hub.docker.com/r/derhuerst/db-rest/)
 [![dependency status](https://img.shields.io/david/derhuerst/db-rest.svg)](https://david-dm.org/derhuerst/db-rest)
 ![ISC-licensed](https://img.shields.io/github/license/derhuerst/db-rest.svg)