document on-board passenger information APIs

[derhuerst]

In https://github.com/derhuerst/live-icomera-position/issues/3, @Adwirawien proposed to have a central place to collect machine-readable knowledge about on-board (as in: available in the vehicle-local WiFi) APIs:

[...] I [...] noticed the wifi-on-ice-portal-client as well as digital-im-regio-portal-client and a few others. From what I can tell they are more or less all using the same icomera api with a few exceptions.

[...] This would prevent the sort of chaos, that we're noticing regarding public transport information apis and could act as a central place for documentation of all the available on-board information systems.

[...] it would be useful to have a central place, much like what WoBike is for bike/scooter sharing APIs, or transport-apis.

Let's focus the discussion here on how to add data to transport-apis, and keep the general discussion on how to obtain it and potential future projects building on top over at https://github.com/derhuerst/live-icomera-position/issues/3.

What do you think @derf?

[derf]

:+1: Sounds good to me. Of course, in-vehicle APIs are somewhat different as they're not accessible from the outside and may depend on the local network setup, but I think we can handle that.

Judging from the discussion at https://github.com/derhuerst/live-icomera-position/issues/3, there are API instances where the endpoint depends on the network setup (e.g. it's located on the default gateway). Do we need support for some kind of relative endpoint definition, as in {default_gateway}/api? For WifionICE, it's (also?) possible to use https://iceportal.de/api1, but I don't know if DNS is available in general.

Also, we should clearly document that these APIs are not accessible from the outside to minimize confusion.

[hannsadrian]

From what I've seen, the onboard apis are mostly available under a few different domains as well as the standard gateway. However, in the Czech Railways trains for example the standard gateway simply redirects to cdwifi.cz. I can imagine similar behavior on other onboard systems. I think locally overwritten DNS entries are available most of the time and we don't need to mess around with gateway ips too much.

[derhuerst]

I'd prefer to document the individual API calls/endpoints as relatice URLs (e.g. /train-position) and separate them from the base address. This would have several benefits:

• There are often multiple way to reach the APIs.
• It has greater flexibility when specifying things like using local DNS.

[derf]

Good point. We could use something like this (perhaps with more appropriate key names, I just can't think of any right now).

{
  "endpoint": "/api1/train-position",
  "entrypoints": [{"host": "iceportal.de", "https": true}, {"host": "192.168.0.1", "https": false}, {"gateway": true, "https": false}]
}

→ The train-position API is typically available on iceportal.de, 192.168.0.1, or the default gateway (whichever IP it may be). For this example, I'm assuming that there may be API instances which do not have (proper) TLS certificates and should be accessed via HTTP instead. We might also use "protocol": "http" / "https" to allow for more than just HTTP / HTTPS in the future.

[derhuerst]

We could use something like this (perhaps with more appropriate key names, I just can't think of any right now).

{
  "endpoint": "/api1/train-position",
  "entrypoints": [{"host": "iceportal.de", "https": true}, {"host": "192.168.0.1", "https": false}, {"gateway": true, "https": false}]
}

Looks good to me! I'd argue that, until we really understand what kinds of systems are there and what API calls they support, we might have to specify their API endpoints/calls individually, hence have and array of of endpoints.

→ The train-position API is typically available on iceportal.de, 192.168.0.1, or the default gateway (whichever IP it may be). For this example, I'm assuming that there may be API instances which do not have (proper) TLS certificates and should be accessed via HTTP instead.

I concluded the same from your example, so 👍 for readability.

We might also use "protocol": "http" / "https" to allow for more than just HTTP / HTTPS in the future.

I prefer that, it doesn't lack expressiveness but is easier to process.

[vkrause]

Should we also record the respective Wifi names? That makes it easier to determine which APIs to try for a multi-protocol client.

[hannsadrian]

Seems like not much additional effort and would add value at the same time. Definitely a thing we should do.

[hannsadrian]

It's been a while, but I created a small command line tool that looks for onboard apis in the network you're connected to. At the moment it just uses @derhuerst's libraries. Of course, many more can be easily implemented. Feel free to have a look @adwirawien/onboard-api-discovery.

If you have special knowledge to share about reverse engineering apis, it'd be really awesome if you could contribute them to the repo in written form. I will personally dive into this topic over the next few months too and create a starting point for people who want to have a deeper look in the apis of their public transport vehicles.

[hannsadrian]

I have now added a basic guide for reverse engineering to the repo among with some dumps I gathered from a České dráhy train. Information in the repos readme was also updated.

What do you think @derhuerst, do you have any additional suggestions?

[derhuerst]

It just came to my mind that we could use OpenAPI (whenever applicable) to document these APIs; It also splits an API spec into API Endpoints and API Servers.