Merge pull request #5339 from ibi-group/graphql-move

Move GTFS GraphQL API out of the sandbox

.github/workflows/cibuild.yml

@@ -152,7 +152,7 @@ jobs:
           # schema hasn't changed.
           # example commit: https://github.com/opentripplanner/docs/commit/45e6ddf8e4a4
           
-          SCHEMA_FILE_MODIFIED=`git log -n 1 --pretty=format:%ct src/ext/resources/gtfsgraphqlapi/schema.graphqls`
+          SCHEMA_FILE_MODIFIED=`git log -n 1 --pretty=format:%ct src/main/resources/org/opentripplanner/apis/gtfs/schema.graphqls`
           echo "schema modified at ${SCHEMA_FILE_MODIFIED}"
           git checkout $LOCAL_BRANCH
           DOCS_MODIFIED=`git log -n 1 --pretty=format:%ct api/dev-2.x/graphql-gtfs/introduction.html`
@@ -179,7 +179,7 @@ jobs:
         with:
           node-version: 16
       - name: Run code generator
-        working-directory: src/ext/java/org/opentripplanner/ext/gtfsgraphqlapi/generated
+        working-directory: src/main/java/org/opentripplanner/apis/gtfs/generated
         run: |
           yarn install
           yarn generate

doc-templates/GraphQL-Tutorial.md

@@ -8,10 +8,10 @@
 # GraphQL tutorial
 
 This document will give you a quick start tutorial on how to get started with OTP's GraphQL APIs. For 
-this tutorial we will be using the [GTFS GraphQL API](sandbox/GtfsGraphQlApi.md) as this is the most commonly used one.
+this tutorial we will be using the [GTFS GraphQL API](GTFS-GraphQL-API.md) as this is the most commonly used one.
 
 First of all, make sure that you've loaded street and transit data into your instance by following
-the [basic tutorial](Basic-Tutorial.md)
+the [basic tutorial](../Basic-Tutorial.md)
 
 ## Visual GraphQL API client
 
@@ -20,7 +20,7 @@ started OTP, visit [http://localhost:8080/graphiql](http://localhost:8080/graphi
 
 It should look like this:
 
-![GraphiQL](images/graphiql.png)
+![GraphiQL](../images/graphiql.png)
 
 ## Sending your first query
 
@@ -35,12 +35,12 @@ side panel.
 Now would be a good time to explore the auto-complete capabilities of the tool by moving the
 cursor into the query panel and hitting Ctrl-Space to see what other query parameters are possible.
 
-![GraphiQL](images/graphiql-autocomplete.png)
+![GraphiQL](../images/graphiql-autocomplete.png)
 
 The explorer also has documentation built into it. If you hover your pointer over a property on the 
 left hand side you can see its documentation.
 
-![GraphiQL](images/graphiql-documentation.png)
+![GraphiQL](../images/graphiql-documentation.png)
 
 ## A more advanced query
 
@@ -51,4 +51,4 @@ Most people want to get routing results out of OTP, so lets see the query for th
 Again, please use the autocomplete and documentation viewers to figure out what each input parameter
 and property means.
 
-More examples for a variety of queries can also be found [in the test code](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/src/ext-test/resources/gtfsgraphqlapi/queries).
+More examples for a variety of queries can also be found [in the test code](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/src/test/resources/org/opentripplanner/apis/gtfs/queries).

docs/Basic-Tutorial.md

@@ -201,4 +201,4 @@ You can run the OTP .jar file with the `--help` option for a full list of comman
 
 ## Exploring the API
 
-If you want to learn how to use OTP's API's, check out the [GraphQL tutorial](GraphQL-Tutorial.md).
+If you want to learn how to use OTP's API's, check out the [GraphQL tutorial](apis/GraphQL-Tutorial.md).

docs/Configuration.md

@@ -228,7 +228,7 @@ Here is a list of all features which can be toggled on/off and their default val
 | `ConsiderPatternsForDirectTransfers` | Enable limiting transfers so that there is only a single transfer to each pattern.                                                                                                                        |         ✓️         |         |
 | `DebugClient`                        | Enable the debug web client located at the root of the web server.                                                                                                                                        |         ✓️         |         |
 | `FloatingBike`                       | Enable floating bike routing.                                                                                                                                                                             |         ✓️         |         |
-| `GtfsGraphQlApi`                     | Enable GTFS GraphQL API.                                                                                                                                                                                  |         ✓️         |    ✓️   |
+| `GtfsGraphQlApi`                     | Enable GTFS GraphQL API.                                                                                                                                                                                  |         ✓️         |         |
 | `MinimumTransferTimeIsDefinitive`    | If the minimum transfer time is a lower bound (default) or the definitive time for the transfer. Set this to `true` if you want to set a transfer time lower than what OTP derives from OSM data.         |                    |         |
 | `OptimizeTransfers`                  | OTP will inspect all itineraries found and optimize where (which stops) the transfer will happen. Waiting time, priority and guaranteed transfers are taken into account.                                 |         ✓️         |         |
 | `ParallelRouting`                    | Enable performing parts of the trip planning in parallel.                                                                                                                                                 |                    |         |

docs/SandboxExtension.md

@@ -14,7 +14,6 @@ provided "as is".
 - [Geocoder API](sandbox/GeocoderAPI.md) - Adds an API to search for corners, stops and stations.
 - [Transfer analyser](sandbox/transferanalyzer.md) - Module used for analyzing the transfers between 
 nearby stops generated by routing via OSM data.
-- [GTFS GraphQL API](sandbox/GtfsGraphQlApi.md) - HSL's GraphQL API used by the Digitransit project.
 - [Transmodel API](sandbox/TransmodelApi.md) - Enturs GraphQL Transmodel API.
 - [SIRI Updater](sandbox/SiriUpdater.md) - Update OTP with realtime information from a Transmodel SIRI data source.
 - [SIRI Azure Updater](sandbox/SiriAzureUpdater.md) - fetch SIRI realtime data through *Azure Service Bus*

docs/Version-Comparison.md

@@ -136,7 +136,7 @@ GraphQL API, the only supported way of sending requests to the OTP routing engin
 Details of those two APIs are available at the following pages:
 
 
-- [GTFS GraphQL API](sandbox/GtfsGraphQlApi.md) - HSL's GraphQL API used by the Digitransit
+- [GTFS GraphQL API](apis/GTFS-GraphQL-API.md) - HSL's GraphQL API used by the Digitransit
   project.
 - [Transmodel API](sandbox/TransmodelApi.md) - Entur´s Transmodel API
 

docs/Apis.md → docs/apis/Apis.md

@@ -2,23 +2,23 @@
 
 Several services are built upon OTP's routing and transit data indexing engines. They expose these APIs:
 
-The [GTFS GraphQL API](sandbox/GtfsGraphQlApi.md) has been used by the Digitransit and otp-react-redux 
+The [GTFS GraphQL API](GTFS-GraphQL-API.md) has been used by the Digitransit and otp-react-redux 
 projects as a general purpose routing and transit data API in production for many years. 
 If your input data is mostly GTFS then this is probably the best choice as it uses the same vocabulary.
 
-The [Transmodel GraphQL API](sandbox/TransmodelApi.md) is used at
+The [Transmodel GraphQL API](../sandbox/TransmodelApi.md) is used at
 Entur in production since 2020. Like the GTFS GraphQL API it is also a general purpose API.
 If your input data is mostly NeTeX then you might want to investigate
 this API as it uses the [Transmodel vocabulary](https://en.wikipedia.org/wiki/Transmodel) to describe 
 its entities.
 
-The [Vector tiles API](sandbox/MapboxVectorTilesApi.md) is a special purpose API for displaying
+The [Vector tiles API](../sandbox/MapboxVectorTilesApi.md) is a special purpose API for displaying
 entities on a vector map.
 
-The [Actuator API](sandbox/ActuatorAPI.md) provides endpoints for checking the health status of the
+The [Actuator API](../sandbox/ActuatorAPI.md) provides endpoints for checking the health status of the
 OTP instance and reading live application metrics. 
 
-The [Geocoder API](sandbox/GeocoderAPI.md) allows you to geocode street corners and stop names.
+The [Geocoder API](../sandbox/GeocoderAPI.md) allows you to geocode street corners and stop names.
 
 ## Legacy APIs (to be removed)
 

docs/apis/GTFS-GraphQL-API.md

@@ -0,0 +1,43 @@
+# GTFS GraphQL API
+
+The GTFS GraphQL API is a general purpose API which was created for the Digitransit project and is 
+used heavily by [digitransit-ui](https://github.com/HSLdevcom/digitransit-ui).
+
+[otp-react-redux](https://github.com/opentripplanner/otp-react-redux) has also migrated to this API in 2023.
+
+## URLs 
+ - GraphQL endpoint: [`http://localhost:8080/otp/routers/default/index/graphql`](http://localhost:8080/otp/routers/default/index/graphql)
+ - HTML schema documentation: [https://docs.opentripplanner.org/api/dev-2.x/graphql-gtfs/](https://docs.opentripplanner.org/api/dev-2.x/graphql-gtfs/)
+ - Built-in visual GraphQL client: [http://localhost:8080/graphiql](http://localhost:8080/graphiql)
+
+## Built-in API client
+
+A browser based GraphQL API client is available at [http://localhost:8080/graphiql](http://localhost:8080/graphiql)
+
+![GraphiQL](../images/graphiql.png)
+
+**`curl` example**
+
+A complete example that fetches the list of all stops from OTP is:
+
+```
+curl --request POST \
+  --url http://localhost:8080/otp/routers/default/index/graphql \
+  --header 'Content-Type: application/json' \
+  --header 'OTPTimeout: 180000' \
+  --data '{"query":"query stops {\n  stops {\n    gtfsId\n    name\n  }\n}\n","operationName":"stops"}'
+```
+## Configuration
+
+The API is enabled by default.
+
+If you want to disable it, do it in `otp-config.json`:
+
+```json
+// otp-config.json
+{
+  "otpFeatures" : {
+    "GtfsGraphQlApi": false
+  }
+}
+```

docs/GraphQL-Tutorial.md → docs/apis/GraphQL-Tutorial.md

@@ -8,10 +8,10 @@
 # GraphQL tutorial
 
 This document will give you a quick start tutorial on how to get started with OTP's GraphQL APIs. For 
-this tutorial we will be using the [GTFS GraphQL API](sandbox/GtfsGraphQlApi.md) as this is the most commonly used one.
+this tutorial we will be using the [GTFS GraphQL API](GTFS-GraphQL-API.md) as this is the most commonly used one.
 
 First of all, make sure that you've loaded street and transit data into your instance by following
-the [basic tutorial](Basic-Tutorial.md)
+the [basic tutorial](../Basic-Tutorial.md)
 
 ## Visual GraphQL API client
 
@@ -20,7 +20,7 @@ started OTP, visit [http://localhost:8080/graphiql](http://localhost:8080/graphi
 
 It should look like this:
 
-![GraphiQL](images/graphiql.png)
+![GraphiQL](../images/graphiql.png)
 
 ## Sending your first query
 
@@ -54,12 +54,12 @@ side panel.
 Now would be a good time to explore the auto-complete capabilities of the tool by moving the
 cursor into the query panel and hitting Ctrl-Space to see what other query parameters are possible.
 
-![GraphiQL](images/graphiql-autocomplete.png)
+![GraphiQL](../images/graphiql-autocomplete.png)
 
 The explorer also has documentation built into it. If you hover your pointer over a property on the 
 left hand side you can see its documentation.
 
-![GraphiQL](images/graphiql-documentation.png)
+![GraphiQL](../images/graphiql-documentation.png)
 
 ## A more advanced query
 
@@ -127,4 +127,4 @@ Most people want to get routing results out of OTP, so lets see the query for th
 Again, please use the autocomplete and documentation viewers to figure out what each input parameter
 and property means.
 
-More examples for a variety of queries can also be found [in the test code](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/src/ext-test/resources/gtfsgraphqlapi/queries).
+More examples for a variety of queries can also be found [in the test code](https://github.com/opentripplanner/OpenTripPlanner/tree/dev-2.x/src/test/resources/org/opentripplanner/apis/gtfs/queries).

docs/sandbox/TransmodelApi.md

@@ -73,7 +73,7 @@ at: `http://localhost:8080/otp/routers/default/transmodel/index/graphql`
 ### OTP2 Official GraphQL API (Not available)
 
 We **plan** to make a new offical OTP2 API, replacing the REST API. The plan is to base the new API
-on this API and the [GTFS GraphQL API](GtfsGraphQlApi.md). The new API will most likely have two
+on this API and the [GTFS GraphQL API](../apis/GTFS-GraphQL-API.md). The new API will most likely have two
 "translations": A GTFS version and a Transmodel version, we will try to keep the semantics the same.
 
 ### Configuration

magidoc.mjs

@@ -1,7 +1,7 @@
 export default {
   introspection: {
     type: 'sdl',
-    paths: ['src/ext/resources/gtfsgraphqlapi/schema.graphqls'],
+    paths: ['src/main/resources/org/opentripplanner/apis/gtfs/schema.graphqls'],
   },
   website: {
     template: 'carbon-multi-page',
@@ -24,12 +24,12 @@ at http://localhost:8080/graphiql
 
 ![GraphiQL screenshot](https://docs.opentripplanner.org/en/dev-2.x/images/graphiql.png)
 
-## Activation
+## Configuration
 
-This API used to be off by default but since June '23 that has changed.
+This API is activated by default.
 
 To learn how to deactivate it, read the
-[documentation](https://docs.opentripplanner.org/en/dev-2.x/sandbox/GtfsGraphQlApi/).
+[documentation](https://docs.opentripplanner.org/en/dev-2.x/apis/GTFS-GraphQ-API/).
 `,
       }],
       appTitle: 'OTP GTFS GraphQL API',