API Improvements

[felixguendling]

Idea:

• for incoming messages: move union type from inside JSON object to outside (for Flatbuffers to parse)
• for outgoing messages: move union type from outside JSON to inside the object (for OpenAPI tools, etc.)

This would enable OpenAPI and better tooling support for working with the MOTIS JSON via HTTP API.

Also: remove target (module / topic) or move it into the HTTP path.

More API ideas:

• Generate OpenAPI from fbs (requires defining a service interface: request/response types per endpoint)
• Generate Documentation from fbs
• JWT for limiting access to certain API functions (like RT updates) - currently only possible to limit access via external proxies
• generate API code in module from OpenAPI description, annotated by access control
• versioning /v0/routing etc.
• support for externally defined existing standardized stable APIs /SIRI/v2.0

[derhuerst]

My personal opinion on some of these proposals:

• JWT for limiting access to certain API functions (like RT updates) - currently only possible to limit access via external proxies

I'd argue that whoever has the resources and expertise to run a MOTIS instance will be fine managing an HTTP proxy in front of it. Also, people might ask for other auth mechanisms soon, so this is a bit of a slippery slope.

• versioning /v0/routing etc.

It's good to have a strategy for versioning in place up front, a technical way to introduce backwards-incompatible changes in a not-immediately-breaking way.

But I wouldn't go further than that: Only make use of the mechanism as soon as a situation really demands it. As long as you can reasonably expect people to switch to a new (backwards-incompatible) MOTIS release in order to use a new feature, try to avoid supporting multiple versions.

• support for externally defined existing standardized stable APIs /SIRI/v2.0

Is SIRI really standardised enough to spend time on creating a server for it in MOTIS? AFAIK there are multiple "flavours" in use.

[felixguendling]

Thank you for your feedback! :+1:

You're right, JWT is only one option. But I think in general that we need to make certain API paths internal by default because they allow to modify delays, cancel trains, etc. This will probably come with the next release.

I agree, there should be a deprecation policy to fade out old versions of the API gracefully.

Even if SIRI is not standardized enough for being considered stable, I really like the idea of supporting a "neutral" API that's not vendor-specific. Currently, every platform has its own format without any guaranty on stability. Switching backends forces huge rewrites in frontend applications. So I think anything that's standardized and documented by a neutral entity like VDV should be more reliable than what we make up on our own. The current format in MOTIS will still be supported. Even if SIRI still changes, I would not expect it to change fundamentally.

Again thank you very much for providing your opinion!

[derhuerst]

(this is off-topic now, feel free to ignore it)

[…] anything that's standardized and documented by a neutral entity like VDV should be more reliable than what we make up on our own.

IMO VDV isn't really neutral, it is way too influenced by corporate members of the working groups, and VDV standards aren't as mature as I initially thought they would be.