New methods to get referenced items by id

[ialokim]

As defined by the FPTF spec

you may choose whether to reference an item by its id or inline the item as an object.

If a module adhering to the FTPI returns data containing such references, the user will likely want to be able to query the item using the given id. Therefore, I propose to add a couple of new methods to the interface specification:

• stations.get(id)
• stops.get(id)
• regions.get(id) (not sure if this one should be required if the underlaying endpoint does not have a concept of regions?)
• lines.get(id)
• routes.get(id)
• schedules.get(id) (see also the ongoing discussions regarding the schedule item in FTPF#5 and FTPF#42)
• operators.get(id)
• locations.get(id) (not sure if this item can be referenced, as the spec doesn't require an id for location?)

The hafas-client already provides a similar method for stations.

[ialokim]

Any comments?

[juliuste]

Somehow I must have overlooked the notification for this, I'm sorry 🤭

Since FPTF 2 will probably bring a major overhaul to some types, in part to enable us to do the exact thing you propose (e.g. with trip and leg) for modules like hafas-client, I would prefer just to add this for

• stations
• stops
• regions
• stopovers
• journeys

which are the types contained within FPTI so far for now, if this ok for you?

• regions.get(id) (not sure if this one should be required if the underlaying endpoint does not have a concept of regions?)

I'm not sure what you mean here, since all FPTI methods are optional for now, we just say that modules have to use this name/signature if they can provide the data, as stated in the spec:

While most libraries certainly don't cover all of the following features, the basic principle for modules complying to fpti-js is that if a certain feature is available, it must be provided with the API described below. Some modules may also include additional functionalities that are not covered within this specification, as long as they don't use the reserved fpti-js method names

[juliuste]

I'd slightly prefer station instead of stations.get etc. though because I would rather not change the current journeys to something like journeys.search just to make everything look the same.