Merge pull request #265 from HSLdevcom/graphiql-deployment-doc-changes

DT-6515 GraphiQL deployment doc changes and add new favicon

README.md

@@ -6,10 +6,9 @@ Digitransit marketing site built using [Gatsby][Gatsby] static site generator.
 
 ## Development workflow
 
-1. Install gatsby as a dependency using: `yarn global add [email protected]`
-2. Install dependencies by running: `yarn`
-3. Start development server using: `gatsby develop`
-4. Build production version using: `gatsby build`
+1. Install dependencies by running: `yarn install`
+2. Start development server using: `yarn gatsby develop`
+3. Build production version using: `yarn gatsby build`
 
 ## Licensing
 

src/components/SEO.js

@@ -48,7 +48,7 @@ export default ({ pageTitle, pageDescription, pagePath }) => (
           <title>{title}</title>
           <meta name="description" content={description} />
           <link rel="canonical" href={canonicalUrl} />
-          <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+          <link rel="icon" type="image/png" href="/favicon.png" />
         </Helmet>
       );
     }}

src/pages/en/developers/apis/1-routing-api/0-graphql/index.md

@@ -266,7 +266,7 @@ Two commonly used GraphQL clients are
 
 ### GraphQL schema
 
-The current development version of the schema is available [here](https://raw.githubusercontent.com/HSLdevcom/OpenTripPlanner/refs/heads/dev-2.x/application/src/main/resources/org/opentripplanner/apis/gtfs/schema.graphqls). It might not always match the production version completely. The production schema can be accessed either by browsing the files from our latest [release in Github](https://github.com/HSLdevcom/OpenTripPlanner/releases) or by running [this example in GraphQL console](<https://api.digitransit.fi/graphiql/hsl/v2?query=query%2520IntrospectionQuery%2520%257B%250A%2520%2520__schema%2520%257B%250A%2520%2520%2520%2520queryType%2520%257B%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520mutationType%2520%257B%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520subscriptionType%2520%257B%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520types%2520%257B%250A%2520%2520%2520%2520%2520%2520...FullType%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520directives%2520%257B%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520description%250A%2520%2520%2520%2520%2520%2520locations%250A%2520%2520%2520%2520%2520%2520args%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520...InputValue%250A%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%257D%250A%2520%2520%257D%250A%257D%250A%250Afragment%2520FullType%2520on%2520__Type%2520%257B%250A%2520%2520kind%250A%2520%2520name%250A%2520%2520description%250A%2520%2520fields%28includeDeprecated%253A%2520true%29%2520%257B%250A%2520%2520%2520%2520name%250A%2520%2520%2520%2520description%250A%2520%2520%2520%2520args%2520%257B%250A%2520%2520%2520%2520%2520%2520...InputValue%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520type%2520%257B%250A%2520%2520%2520%2520%2520%2520...TypeRef%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520isDeprecated%250A%2520%2520%2520%2520deprecationReason%250A%2520%2520%257D%250A%2520%2520inputFields%2520%257B%250A%2520%2520%2520%2520...InputValue%250A%2520%2520%257D%250A%2520%2520interfaces%2520%257B%250A%2520%2520%2520%2520...TypeRef%250A%2520%2520%257D%250A%2520%2520enumValues%28includeDeprecated%253A%2520true%29%2520%257B%250A%2520%2520%2520%2520name%250A%2520%2520%2520%2520description%250A%2520%2520%2520%2520isDeprecated%250A%2520%2520%2520%2520deprecationReason%250A%2520%2520%257D%250A%2520%2520possibleTypes%2520%257B%250A%2520%2520%2520%2520...TypeRef%250A%2520%2520%257D%250A%257D%250A%250Afragment%2520InputValue%2520on%2520__InputValue%2520%257B%250A%2520%2520name%250A%2520%2520description%250A%2520%2520type%2520%257B%250A%2520%2520%2520%2520...TypeRef%250A%2520%2520%257D%250A%2520%2520defaultValue%250A%257D%250A%250Afragment%2520TypeRef%2520on%2520__Type%2520%257B%250A%2520%2520kind%250A%2520%2520name%250A%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520kind%250A%2520%2520%2520%2520name%250A%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%257D%250A%2520%2520%257D%250A%257D%250A&operationName=IntrospectionQuery>)
+The current development version of the schema is available [here](https://raw.githubusercontent.com/HSLdevcom/OpenTripPlanner/refs/heads/dev-2.x/application/src/main/resources/org/opentripplanner/apis/gtfs/schema.graphqls). It might not always match the production version completely. The production schema can be accessed either by browsing the files from our latest [release in Github](https://github.com/HSLdevcom/OpenTripPlanner/releases) or by running [this example in GraphQL console](<https://api.digitransit.fi/graphiql/hsl/v2/gtfs/v1?query=query%2520IntrospectionQuery%2520%257B%250A%2520%2520__schema%2520%257B%250A%2520%2520%2520%2520queryType%2520%257B%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520mutationType%2520%257B%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520subscriptionType%2520%257B%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520types%2520%257B%250A%2520%2520%2520%2520%2520%2520...FullType%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520directives%2520%257B%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520description%250A%2520%2520%2520%2520%2520%2520locations%250A%2520%2520%2520%2520%2520%2520args%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520...InputValue%250A%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%257D%250A%2520%2520%257D%250A%257D%250A%250Afragment%2520FullType%2520on%2520__Type%2520%257B%250A%2520%2520kind%250A%2520%2520name%250A%2520%2520description%250A%2520%2520fields%28includeDeprecated%253A%2520true%29%2520%257B%250A%2520%2520%2520%2520name%250A%2520%2520%2520%2520description%250A%2520%2520%2520%2520args%2520%257B%250A%2520%2520%2520%2520%2520%2520...InputValue%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520type%2520%257B%250A%2520%2520%2520%2520%2520%2520...TypeRef%250A%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520isDeprecated%250A%2520%2520%2520%2520deprecationReason%250A%2520%2520%257D%250A%2520%2520inputFields%2520%257B%250A%2520%2520%2520%2520...InputValue%250A%2520%2520%257D%250A%2520%2520interfaces%2520%257B%250A%2520%2520%2520%2520...TypeRef%250A%2520%2520%257D%250A%2520%2520enumValues%28includeDeprecated%253A%2520true%29%2520%257B%250A%2520%2520%2520%2520name%250A%2520%2520%2520%2520description%250A%2520%2520%2520%2520isDeprecated%250A%2520%2520%2520%2520deprecationReason%250A%2520%2520%257D%250A%2520%2520possibleTypes%2520%257B%250A%2520%2520%2520%2520...TypeRef%250A%2520%2520%257D%250A%257D%250A%250Afragment%2520InputValue%2520on%2520__InputValue%2520%257B%250A%2520%2520name%250A%2520%2520description%250A%2520%2520type%2520%257B%250A%2520%2520%2520%2520...TypeRef%250A%2520%2520%257D%250A%2520%2520defaultValue%250A%257D%250A%250Afragment%2520TypeRef%2520on%2520__Type%2520%257B%250A%2520%2520kind%250A%2520%2520name%250A%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520kind%250A%2520%2520%2520%2520name%250A%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520ofType%2520%257B%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520kind%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520name%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%2520%2520%257D%250A%2520%2520%2520%2520%257D%250A%2520%2520%257D%250A%257D%250A&operationName=IntrospectionQuery>)
 
 ## Further reading
 

src/pages/en/developers/apis/1-routing-api/1-graphiql/index.md

@@ -9,36 +9,20 @@ order: 20
 
 [GraphiQL](https://github.com/graphql/graphiql) is a simple UI for making queries. You can use it both to run queries and to explore the GraphQL schema.
 
-**Note:** All top level queries should have at least some description available and you can use the documentation explorer to familiarize yourself with the schema. You can find more details about that under [Reading schema docs](#reading-schema-docs).
+**Note:** Queries, parameters, and fields should have at least some description available and you can use the documentation explorer to familiarize yourself with the schema. You can find more details about that under [Reading schema docs](#reading-schema-docs).
 
-### There are a few options for using GraphiQL:
+### Using the Digitransit GraphiQL browser versions
 
-1. Using our hosted browser versions for the five available regions. The browser versions have the correct endpoints configured already.
-   * [Helsinki region](https://api.digitransit.fi/graphiql/hsl)
-   * [Waltti regions](https://api.digitransit.fi/graphiql/waltti)
-   * [Waltti-Opas regions](https://api.digitransit.fi/graphiql/waltti-alt)
-   * [Seutu+ regions](https://api.digitransit.fi/graphiql/varely)
-   * [Entire Finland](https://api.digitransit.fi/graphiql/finland)
-2. A browser extension like [ChromeiQL](https://chrome.google.com/webstore/detail/chromeiql/fkkiamalmpiidkljmicmjfbieiclmeij) (see regional endpoints below)
-3. For Mac OSX you can use [the desktop GraphiQL app](https://github.com/skevy/graphiql-app) (see regional endpoints below)
-
-All options work similarly and their UI looks more or less like this (ChromeiQL extension has been used in the example below):
-
-![GraphiQL](./GraphiQL.png)
+You can use our hosted GraphiQL browser versions for the five available regions. The browser versions have the correct endpoints configured.
+   * [Helsinki region](https://api.digitransit.fi/graphiql/hsl/v2/gtfs/v1)
+   * [Waltti regions](https://api.digitransit.fi/graphiql/waltti/v2/gtfs/v1)
+   * [Waltti-Opas regions](https://api.digitransit.fi/graphiql/waltti-alt/v2/gtfs/v1)
+   * [Seutu+ regions](https://api.digitransit.fi/graphiql/varely/v2/gtfs/v1)
+   * [Finland and Estonia](https://api.digitransit.fi/graphiql/finland/v2/gtfs/v1)
 
 ## Execute your first query
 
-1. If you are using the GraphiQL app or a browser extension, set the GraphQL Endpoint to one of the following:
-
-| Region              | Endpoint                                                                 |
-|---------------------|--------------------------------------------------------------------------|
-| Helsinki region     | `https://api.digitransit.fi/routing/v2/hsl/gtfs/v1`        |
-| Waltti regions      | `https://api.digitransit.fi/routing/v2/waltti/gtfs/v1`     |
-| Waltti-Opas region  | `https://api.digitransit.fi/routing/v2/waltti-alt/gtfs/v1` |
-| Seutu+ region       | `https://api.digitransit.fi/routing/v2/varely/gtfs/v1`     |
-| Entire Finland      | `https://api.digitransit.fi/routing/v2/finland/gtfs/v1`    |
-
-2. Click [this link](https://api.digitransit.fi/graphiql/hsl?query=%7B%0A%20%20stop(id%3A%20%22HSL%3A1040129%22)%20%7B%0A%20%20%20%20name%0A%20%20%20%20lat%0A%20%20%20%20lon%0A%20%20%20%20wheelchairBoarding%0A%20%20%7D%0A%7D) to run the query below in GraphiQL.
+1. Click [this link](https://api.digitransit.fi/graphiql/hsl/v2/gtfs/v1?query=%7B%0A%20%20stop(id%3A%20%22HSL%3A1040129%22)%20%7B%0A%20%20%20%20name%0A%20%20%20%20lat%0A%20%20%20%20lon%0A%20%20%20%20wheelchairBoarding%0A%20%20%7D%0A%7D) to run the query below in GraphiQL.
 
 ```graphql
 {
@@ -51,9 +35,11 @@ All options work similarly and their UI looks more or less like this (ChromeiQL
 }
 ```
 
-3. Press play in GraphiQL to execute the query.
+2. Press play in GraphiQL to execute the query.
+
+![GraphiQL](./GraphiQL.png)
 
-4. You should get results like below:
+3. You should get results like below:
 
 ```json
 {
@@ -69,27 +55,45 @@ All options work similarly and their UI looks more or less like this (ChromeiQL
 ```
 **Note:** If the example provided does not return what is expected then the stop id used in step 2 may not be in use any more and you should try again with an existing id.
 
-## Exploring schema with GraphiQL
+## Changing the endpoint or API type
+
+When using the browser version, the endpoint currently in use can be viewed by hovering over the **EP** icon.
+
+![GraphiQL](./GraphiQL-endpoint-hovering.png)
+
+The endpoint can be changed by clicking the **EP** icon. A menu with endpoint options opens up.
+
+![GraphiQL](./GraphiQL-endpoint.png)
+
+The API type currently in use can be viewed by hovering over the **API** icon.
+
+![GraphiQL](./GraphiQL-api-hovering.png)
+
+The API type can be changed by clicking the **API** icon. A menu with API type options opens up. Only the production API type is intended for public use. The development API type has a schema which is not stable and can be subject to change.
+
+![GraphiQL](./GraphiQL-api.png)
+
+## Exploring the schema with GraphiQL
 
 GraphiQL is schema aware. This means that you can invoke autocomplete by Ctrl-space. The tool then shows available options for your query.
 
 ![GraphiQL](./GraphiQL-autocomplete.png)
 
 ## Reading schema docs
 
-By clicking **< Docs** in the upper right corner of GraphiQL, you can open the **Documentation Explorer**. Then, clicking **query: QueryType** will open up a list of all available top level queries.
+By clicking the documentation icon in the upper left corner of GraphiQL you can open the **Documentation Explorer**. Then, clicking **query: QueryType** will open up a list of all available top level queries.
 
 ![GraphiQL](./GraphiQL-docs.png)
 
-From here you can check e.g. **alerts**, which describes what can be queried using that top level. It says "Get all alerts active in the graph".
+From here you can check e.g. **alerts**, which describes what can be queried using that top level. It says "Get all active alerts".
 
 ![GraphiQL](./GraphiQL-alerts.png)
 
 Let's try to query alerts:
 
 1. Close the docs
 
-2. Click [this link](https://api.digitransit.fi/graphiql/hsl?query=%7B%0A%20%20alerts%20%7B%0A%20%20%20%20alertDescriptionText%0A%20%20%7D%0A%7D) to run the query below in GraphiQL.
+2. Click [this link](https://api.digitransit.fi/graphiql/hsl/v2/gtfs/v1?query=%7B%0A%20%20alerts%20%7B%0A%20%20%20%20alertDescriptionText%0A%20%20%7D%0A%7D) to run the query below in GraphiQL.
 
 ```graphql
 {

src/pages/en/developers/apis/1-routing-api/2-glossary/index.md

@@ -7,7 +7,7 @@ order: 30
 
 | Term                   | Explanation                     |
 |------------------------|---------------------------------|
-| Feed                   | Feeds provide routing data (e.g. stops and timetables) from one or more public transport agencies to the API. List of available feeds can be queried by using [**feeds**](https://api.digitransit.fi/graphiql/finland?query=%7B%0A%20%20feeds%20%7B%0A%20%20%20%20feedId%0A%20%20%20%20agencies%20%7B%0A%20%20%20%20%20%20name%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D) query.
+| Feed                   | Feeds provide routing data (e.g. stops and timetables) from one or more public transport agencies to the API. List of available feeds can be queried by using [**feeds**](https://api.digitransit.fi/graphiql/finland/v2/gtfs/v1?query=%7B%0A%20%20feeds%20%7B%0A%20%20%20%20feedId%0A%20%20%20%20agencies%20%7B%0A%20%20%20%20%20%20name%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D) query.
 | Agency                 | Some public transport provider, e.g. [HSL](https://www.hsl.fi/).
 | Disruption (Alert)     | A temporary change in public transport services.<br/>For example, a stop out-of-use or a diversion on a route.
 | Transportation Mode    | A means of transport, for example: walking, cycling, driving a car, bus, train, subway, tram, ferry, airplane.

src/pages/en/developers/apis/1-routing-api/4-translations/index.md

@@ -21,7 +21,7 @@ at once, for example. In that case, it's possible to fetch the same field multip
 specify the requested language (this overrides the language from the `Accept-Language` header). Here's an example on how to use this on
 vehicle parking:
 
-1. Click [this link](https://api.digitransit.fi/graphiql/hsl/v2?query=%257B%250A%2520%2520vehicleParkings%2520%257B%250A%2520%2520%2520%2520%2520nameFi%253A%2520name%28language%253A%2520%2522fi%2522%29%250A%2520%2520%2520%2520%2520nameSv%253A%2520name%28language%253A%2520%2522sv%2522%29%250A%2520%2520%2520%2520%2520nameEn%253A%2520name%28language%253A%2520%2522en%2522%29%250A%2520%2520%257D%250A%257D) to run the query below in GraphiQL.
+1. Click [this link](https://api.digitransit.fi/graphiql/hsl/v2/gtfs/v1?query=%257B%250A%2520%2520vehicleParkings%2520%257B%250A%2520%2520%2520%2520%2520nameFi%253A%2520name%28language%253A%2520%2522fi%2522%29%250A%2520%2520%2520%2520%2520nameSv%253A%2520name%28language%253A%2520%2522sv%2522%29%250A%2520%2520%2520%2520%2520nameEn%253A%2520name%28language%253A%2520%2522en%2522%29%250A%2520%2520%257D%250A%257D) to run the query below in GraphiQL.
 
 ```graphql
 {