From b83d89562dbc9e60935fa0a85f69aab8ec94bc8e Mon Sep 17 00:00:00 2001 From: Jannis R Date: Sun, 4 Oct 2020 13:46:14 +0200 Subject: [PATCH] =?UTF-8?q?restructure=20docs=20=F0=9F=93=9D,=20status=20b?= =?UTF-8?q?adge?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api.js | 2 +- docs/readme.md | 25 ++++++++++-- docs/why.md | 104 ------------------------------------------------- package.json | 2 +- readme.md | 3 +- 5 files changed, 26 insertions(+), 110 deletions(-) delete mode 100644 docs/why.md diff --git a/api.js b/api.js index 14cd5bd..87bcfd5 100644 --- a/api.js +++ b/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, } diff --git a/docs/readme.md b/docs/readme.md index 8e32211..5103a9a 100644 --- a/docs/readme.md +++ b/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. diff --git a/docs/why.md b/docs/why.md deleted file mode 100644 index c671bcd..0000000 --- a/docs/why.md +++ /dev/null @@ -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. diff --git a/package.json b/package.json index 9546aa9..30757b8 100644 --- a/package.json +++ b/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/index.html && build-technical-doc --syntax-stylesheet-url /syntax.css docs/getting-started.html && build-technical-doc --syntax-stylesheet-url /syntax.css docs/why.html && build-technical-doc --syntax-stylesheet-url /syntax.css 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/index.html && build-technical-doc --syntax-stylesheet-url /syntax.css docs/getting-started.html && build-technical-doc --syntax-stylesheet-url /syntax.css docs/api.html && build-technical-doc --syntax-stylesheet github >docs/syntax.css", "build": "npm run docs", "start": "node index.js" } diff --git a/readme.md b/readme.md index 2f07090..b8dce6b 100644 --- a/readme.md +++ b/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)