Design 2.x API

[drewda]

---

Timing:

• After new core routing components (RAPTOR propagation takes too long #2015) are complete, so we know what API endpoints and query parameters will be possible to support in 2.x.
• After usage inventory (Inventory 1.x API and usage #2621) is complete, so we know what subset of existing API is worth keeping.

[t2gran]

The OTP APIs all depend on the previous implementation of the routing algorithm - AStar. When switching to Raptor, quite a few changes is needed. This apply mostly to the routing request, not the routing response or Index API. The Goal is of cause to keep the APIs as close to what we have, but in some cases the API will change.

Transmodel GraphQL API

At Entur we will revise the Transmodel GraphQL API, to my knowledge Entur and Ruter are the only consumers of this API. We want to do this with the GTFS version of the GraphQL API. We will if necessary break the backward compatibility. The code is based on an early version of the GraphQL framework and we want to define the schema in a schema file, not in Java code. We will also cleanup some of the design mistakes and try to make the API easier to maintain. We will run both the old API and the new API in parallell until all clients are migrated to the new API - this gives us the freedom to BREAK the backward compatibility.

GTFS GraphQL API

At Entur we would like to find an easy way to maintain both GTFS and Transmodel version of the API. One solution would be to have one implementation with 2 translations. This API is used by HSL and in Estonia - so we will of cause coordinate them. Are there any other users?

GTFS Rest API

The Goal is to keep it backward compatible - deprecating a quite a few parameters. Entur will NOT provide some of the new features through this API. We will encourage people to move to the new GraphQL APIs.

Community - Request for change

Revising the APIs also is a golden opportunity to improve. We encourage everyone to submit "feature requests", "thoughts" and "improvements" here, so we can consider them making the new GraphQL APIs. Here is a summary:

• Add generic support on lists to filter and sort.
• Take a look at the Apollo framework and "borrow" server-side enhancements.
• Support for HTTP Header Accept-Language and/or filter to return just preferred language text instead of MultilingualString(See PtSituationElement in Transmodel GraphQL API).
• The Transmodel API have white/black listing of several types(Agency, Route, Trip ...), but the order which these filters is applied is not possible to set. The problem with this is that the order you apply it matters. A possible solution is to use a list of filters instead - something like this:

Request { filter : List<Filter> }
Filter { op : [INCLUDE, EXCLUDE], ids : Set<Id>,  type : [AGENCY, OPERATOR, LINE, STOP ...]}

(I will try to update this list, whenever I get a suggestion)