document on-board passenger information APIs about transport-apis HOT 10 OPEN

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

from transport-apis.

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.

from transport-apis.

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?

from transport-apis.

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.

from transport-apis.

👍 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 derhuerst/live-icomera-position#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.

from transport-apis.

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.

from transport-apis.

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.

from transport-apis.

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.

from transport-apis.

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.

from transport-apis.

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

from transport-apis.