Follow best practices for designing GraphQL APIs. Our APIs need to be backwards compatible as they are used by hundreds of clients (web-pages/apps/services). A good reference used by several of the OTP developers is the Production Ready GraphQL book by Marc-André Giroux.
We use the pagination (a.k. Relay) specification for paging over entities like stations, stops, trips and routes. Very often OTP has a finite list of entities in memory.
We often use type(id) format queries for fetching or refetching entities or value objects of type
by id. Additionally, the GTFS GraphQL API has a node interface and query for refetching objects
which follow the GraphQL Global Object Identification Specification.
We should not use the node interface or query for non-entities (such as Itineraries and Legs) which
do not always have an ID and/or which IDs are not trivial to reconstruct.
Unfortunately, part of the GraphQL API is old and does not follow best practices. So, when adding new features, consider what is best; To follow the existing style or follow the best practice.
Our APIs need to be backwards compatible as they are used by hundreds of clients (web-pages/apps/services). Correcting mistakes may not be possible or may take a long time.
We allow breaking API changes in these cases:
- During incremental development of a new feature (multiple PRs). The new part of the API should be documented as "WorkInProgress - Why/When is it ready". A new API should not stay "open" for a long time.
- Deprecated features can be removed after 2 years (4 minor releases) unless a user wants to keep it. We will revert a removal if the request to keep it comes after the feature is removed. Example:
Use feature xyz instead. Note! This feature is subject for removal in September 2027! If you want this to stay, please notify the OTP community.