one-to-many v2 endpoint

[e-kotov]

Proposal: V2 one-to-many endpoint

This issue proposes a V2 endpoint (/api/v2/one-to-many) to improve consistency with other MOTIS endpoints and improve developer ergonomics.

Proposed Improvements

1. Align time units with one-to-all

Currently, one-to-many uses max in seconds, while one-to-all uses maxTravelTime in minutes (and all other endpoints also mostly use minutes). Also it just does not seem to make much sense to measure time in seconds for travel, and if precision is that important, using decimal minutes should work too.

Proposal: Adopt maxTravelTime (minutes) in V2. This standardizes the API surface and reduces unit-mismatch with other endpoints. Make it easier to understand what max refers to even without reading the API description.

2. Structured response object

The current response is a JSON array: [{"duration": 120}, ...].

Proposal: Wrap the response in a structured object to allow for metadata and future extensibility:

{
  "durations": [ ... ],
  "debugOutput": { ... }
}

This proposal together with the next one are the main reason for 'v2', as the format of the response would change significantly.

3. Add optional debug statistics

For performance profiling (distinguishing network vs. routing latency), client-side measurement is insufficient.

Proposal: Add an optional debug=true parameter.

• Initial implementation: Return server-side timing statistics (e.g., routing: 45ms, parsing: 2ms) in the debugOutput field.
• Future potential: The debugOutput structure provides a place to expose internal routing failure reasons (e.g. "unreachable" vs "disconnected graph") if the underlying osr library exposes them in the future. Because the debug data may contain more data than the useful response with durations and distances (e.g. if debug would contain info for each calculated/non-calculated route), it should be optional.

4. Improve default values

Proposal: Make the following parameters optional with sensible defaults:

• arriveBy: false: The primary use case for one-to-many is computing isochrones/accessibility from a single origin to many destinations (forward search). Defaulting to false creates the "path of least resistance" for the most common task. The reverse operation is probably used less often anyway.
• maxMatchingDistance: 25: one-to-all already has this default, so for consistency I would use it here too. (Even though the web ui uses a much larger 250).

5. Inline mode enum

Currently, mode references the global Mode schema, which includes unsupported modes (like PT).

Proposal: Inline enum: [WALK, BIKE, CAR] for V2. This creates a strict, self-documenting contract. Expanding this list later to include more modes is a non-breaking change. Substituting it later with 'Mode' schema if the endpoint some day supports the whole schema should not be an issue.

Also, I'n not sure if this endpoint should have

Summary of V2 Changes

Feature	V1 (Current)	V2 (Proposed)
Travel Time	max (seconds)	maxTravelTime (minutes)
Response format	Array<Duration>	Object { durations: ... }
Defaults	arriveBy required	Default false
Defaults	maxMatchingDistance required	Default 25
Debug Info	Not available	debug param & output
Modes	Global Mode	Inlined WALK, BIKE, CAR

P.S. Maybe I fundamentally misunderstand something about internals of MOTIS and its components, so maybe some of these suggestions may seem absurd or even counterproductive.

[felixguendling]

First of all: I agree with your points and your changes would create more consistency.

In general:

• People/communities/companies invest a lot of resources (time/money/both) into their client implementation. By making arbitrary changes to make things look more consistent, we force a lot of unnecessary costs on the MOTIS ecosystem. So in general, I'm a bit hesitant to force those changes onto clients - especially in a case like "inconsistent units" or "modes allow more than necessary". Of course clients don't have to switch immediately due to versioned APIs but eventually those costs will be incurred.
• The less API versions we have to maintain in MOTIS, the less maintenance costs we have. Also here, I would be careful not to create maintenance costs for the coming years just to make something a little more consistent (if it worked otherwise).

The learning from this should probably be to force new APIs to be /api/experimental/* for at least one year and/or until a certain number of client implementations "validated" the API design.

Since probably almost no one used this specific API (at least compared to stop times, 1:1 routing, etc.), we might still do those changes. But in general I would weight costs of API switching for clients and maintenance costs for multiple API versions on our side higher than the improved consistency of the API.

Currently, one-to-many uses max in seconds, while one-to-all uses maxTravelTime in minutes

My idea was to try to consistently switch to SI base units (such as meter, second, etc.) at least for new things where we would not introduce inconsistencies.

debug param & output

There's also the standardized Server-Timing HTTP header:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Server-Timing

However, I don't know if this would help us or if there's any tooling support we could leverage for example for Transitous.

But even if we don't do it via the HTTP header, adding this would not require a v2 upgrade of the API.

arriveBy required

Adding a default value to a required parameter is backwards compatible. So we would not need a new API version for this change.

[e-kotov]

People/communities/companies invest a lot of resources (time/money/both) into their client implementation.

I get that! I was thinking about it a lot too. In the past months I have been working on and off on an R client for MOTIS, and I ended up making three separate packages for that, one that generates R packages from OpenAPI 3+ spec (https://github.com/e-kotov/openapi3, and I know about generators such as https://github.com/OpenAPITools/openapi-generator, but they don't work well to my taste), one that generates specifically the R motis.client from the spec using the first one, and finally the 3rd one that wraps the motis.client and provides a user-facing package (https://github.com/e-kotov/rmotis) that has automation for installing the server and configuring it easily from inside R console and running analysis. The logic is that API changes a lot, and I wanted the flexible motis.client to be updated relatively often with many API nobs to tweak, but the rmotis to have several hardcoded documented args (such as to and from ;) ). Anyway, it's the specifics of R and how things are documented. I'm also still not sure this is optimal. All of that is to say that I know that planning for API changes is a pain )

But in general I would weight costs of API switching for clients and maintenance costs for multiple API versions on our side higher than the improved consistency of the API.

That makes total sense.

There's also the standardized Server-Timing HTTP header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Server-Timing

However, I don't know if this would help us or if there's any tooling support we could leverage for example for Transitous.

I did not know about that! I assumed form the plan API that the way debugOutput is done there is the way to go. Thanks.

[PartTimeDataScientist]

But in general I would weight costs of API switching for clients and maintenance costs for multiple API versions on our side higher than the improved consistency of the API.

That makes total sense.

IMHO that depends on the numbers you expect for "clients already using the MOTIS API" vs. "new clients that will use the MOTIS API".

The former are interested in maintenance costs, the latter profit from consistency (i.e. all times in seconds).

As discussed otherwise I'd consider making a one-time "consistency maintenance" release where things like that could be pulled straight on "stable" endpoints. That would provide the opportunity to announce that with enough lead time and with keeping the older endpoints active for some time should allow a slow transition of all still active clients.