Testing locally with ngrok

Using ngrok is a common practice to properly test against your local environment with an API Connect for GraphQL as a Service schema and endpoint.

About this task

ngrok is a tool that opens a tunnel to a web service running on your local machine, so that it can be accessed over the internet. This can be useful for testing your GraphQL endpoints during development, by hosting them directly on your local machine.

ngrok exposes your local server (e.g. localhost:3000) to the public Internet. You can sign up for a free account.

Attention: ngrok exposes your local environment beyond the firewall and NAT of your machine. Even though the environment is exposed through a secure HTTP connection, there can be security vulnerabilities if the public address of your ngrok endpoint is not secured by authorization. Adding Authorization headers to your database or endpoint is recommended to properly test with ngrok.

Procedure

  1. Add ngrok to your local database for the @dbquery directive.

    Install ngrok on your machine by following the instructions in the ngrok dashboard, or run the following brew installation command:

    brew cask install ngrok

    If you use the brew command, there is a forum, that can support you with any errors you run into while installing it.

  2. Create the API Connect for GraphQL as a Service schema for use with ngrok.

    If you already have a schema, skip to Using PostgreSQL with ngrok, Using MySQL with ngrok, or Using a REST API server with ngrok as appropriate.

    1. Generate the API Connect for GraphQL as a Service schema:
      • Mac:
        mkdir Essentials;
cd Essentials;
touch config.yaml;
touch postgres.graphql;
touch index.graphql
      • Windows:
        mkdir Essentials;
cd Essentials;
type nul >> "config.yaml";
type nul >> "postgres.graphql";
type nul >> "index.graphql"
    2. Open index.graphql in your code editor, and add database.graphql to your GraphQL Schema Definition Language (SDL): 
      schema
  @sdl(
    files: [
      "database.graphql"
    ]
  ) {
  query: Query
}