restructure docs 📝, status badge
This commit is contained in:
Jannis R
parent
013a56ba26
commit
b83d89562d
5 changed files with 26 additions and 110 deletions
2
api.js
2
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,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
[](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.
|
||||
|
|
|
|||
104
docs/why.md
104
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.
|
||||
|
|
@ -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"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
||||
|
||||
[](https://stats.uptimerobot.com/57wNLs39M/784879516)
|
||||
[](https://hub.docker.com/r/derhuerst/db-rest/)
|
||||
[](https://david-dm.org/derhuerst/db-rest)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue