Needs for a version 2 of the API

This page references all the misdirected needs. If you want to oppose some idea, just add a pros/cons section to it.

generic

DateTimes

• We forgot to show time zones : "20160929T175000+2"
• "-" are better : "2016-09-29T175000+2"
• same format in requests and responses
• Pay also attention to durations and respect standards on that (like for hour of day)

geoJson

• "/coverage" exposes WKT, there is lots of geoJson : we have to be consistent
• every geoJson are enabled by default: it should be disabled by default, with a "enable_geojson" params
• the ODT lines schemas (and cabs zones) should represent area and not only a stop list

http headers

• with real-time information, a "max-age" information could be nice (with 304 http code implementation?)

coordinate

• to be consistent with GTFS, we should replace "lon" "lat" with "latitude" "longitude" , and be float instead of string

GraphQL

• We have the possibility to activate/deactivate heavy parts of the responses, but maybe using GraphQL can be nice. The cost on response-time and on maintenance has to be watched, though.

notes and exceptions

• For queries "/route_schedules", "/stop_schedules" and "/journeys", there are sections "notes" and "exceptions" at the root-level of the response. The link to these sections should only contain the keys: "id", "internel" and "rel" to avoid info duplication.

services

places

• best management with empty lists: give an empty list :) or a 404

journeys

• replace "forbidden_uris" with "banned_id"
• replace "max_duration_to_pt" with "max_fallback_duration"
• replace "first_section_mode" and "last_section_mode" with "first_fallback_mode" and "last_fallback_mode"
• vehicle position
• rename "crow_fly" with "teleport" when null
• more consistent with "name" vs "label" property. "name" should be for internal uses, "label" to display.
• manage multiple lines doing same route between 2 stop points. For example: from A > take "line 2" or "line 3" > To B
• No_Solution should return a 404, not a 200 like "No_Origin" and others

route_schedules

• replace "forbidden_uris" with "banned_id"
• vehicle position
• flag on exact date when request with a calendar (not a date) and for a cross-midnight VJ

objects

• Have only id everywhere
• code is either stored in codes or in name, but not just as code

Vehicle_journeys

• there are awful