How to Configure the RESTified Endpoints Plugin

Introduction

The RESTified GraphQL endpoints plugin allows you to add RESTified GraphQL endpoints to DDN. This can be used to add custom REST endpoints to DDN that would execute specified GraphQL query on the DDN GraphQL API and return the response.

We're using Cloudflare Wrangler

In this example, we're using Cloudflare Wrangler to deploy our plugin as a Cloudflare Worker. However, you can use any other tool or service that hosts HTTPS services. You can get started with Wrangler here.

Step 1. Create a new plugin project

Create a new Cloudflare Worker project using the create-cloudflare command with the restified-endpoints plugin template:

npx create-cloudflare@latest restified-endpoints-plugin --template https://github.com/hasura/engine-plugin-restified-endpoint

This will create a new project with the required files and dependencies.

Step 2. Install dependencies

Navigate to the new directory and install the dependencies.

cd restified-endpoints-plugin
npm install

Start the local development server.

npm start

Step 3. Add the plugin configuration

We'll let the engine know about the plugin and to execute it as a pre-route plugin by creating a new metadata file. In your global subgraph's metadata directory, create a new file named restified-endpoints.hml and add the following configuration.

kind: LifecyclePluginHook
version: v1
definition:
  pre: route
  name: restified_endpoints
  url:
    valueFromEnv: RESTIFIED_ENDPOINTS_URL
  config:
    match: "/v1/api/rest/*"
    matchMethods: ["GET", "POST"]
    request:
      method: GET
      headers:
        forward:
          - Authorization
          - x-hasura-role
        additional:
          hasura-m-auth:
            valueFromEnv: M_AUTH_KEY
      rawRequest:
        path: {}
        query: {}
        method: {}
        body: {}

URL Match

The match field is used to match the regex to the request path, while matchMethods specifies the HTTP methods to match. In this example, we're matching all GET and POST requests to /v1/api/rest/*. You can modify these to match any path and methods (GET/POST/PUT/PATCH/DELETE) you wish.

Also, note that we can not use the pre-defined DDN endpoints (like /graphql, /v1/sql, /v1/rest, /v1/explain, /healthz and /metrics) in the match field.

Moreover, on DDN cloud, for security reasons, only the /v1/api/rest/* path is allowed for the pre-route plugin.

Using environment variables

We've used valueFromEnv so that we can dynamically and securely add values from our environment variables. You can add these values to your root-level .env and then map them in the globals subgraph.yaml file. Alternatively, you can include raw strings here using value instead of valueFromEnv and passing the keys.

Next, update the subgraph.yaml file to include the metadata file and the environment variables.

kind: Subgraph
version: v2
definition:
  name: globals
  ...
  includePaths:
    ...
    - restified-endpoints.hml
  envMapping:
    RESTIFIED_ENDPOINTS_URL:
      fromEnv: RESTIFIED_ENDPOINTS_URL
    M_AUTH_KEY:
      fromEnv: M_AUTH_KEY

Finally, we need to add the environment variables to the .env file.

RESTIFIED_ENDPOINTS_URL="http://local.hasura.dev:8787"
M_AUTH_KEY="your-strong-m-auth-key"

M-Auth Key

The hasura-m-auth header is a custom header that is used to authenticate the requests to the allowlist plugin. You can use any strong key here to authenticate the plugin. DDN will automatically add this header to the requests to the plugin. Also, make sure to update the src/config.ts file (in step 5) with the same key.

Step 4. Create a new build for local development

Create a new supergraph build.

ddn supergraph build local

Start the console for the local supergraph.

ddn console --local

You can now test the plugin by making a request to the RESTified GraphQL endpoints defined in the plugin's configuration.

Step 5. Update the plugin config

Update the src/config.ts file with the RESTified GraphQL endpoints that you want to add.

export const Config = {
  graphqlServer: {
    url: "http://localhost:3000/graphql",
    headers: {
      additional: {
        "Content-Type": "application/json",
      },
      // Please make sure to forward the authentication headers here
      forward: ["hasura_cloud_pat", "x-hasura-ddn-token"],
    },
  },
  headers: {
    "hasura-m-auth": "your-strong-m-auth-key",
  },
  restifiedEndpoints: [
    ...,
    {
      path: "/v1/api/rest/users",
      methods: ["GET", "POST"],
      query: `
        query MyQuery($limit: Int = 10, $offset: Int = 0) {
          Users(limit: $limit, offset: $offset) {
            Name
          }
        }
      `,
    }
  ],
};

Hot reloading

The local wrangler development server will automatically reload the plugin when you make changes to the code.

Step 6. Configure the plugin variables

Setup tracing

To enable tracing for the plugin, you need to update the wrangler.toml file with the required configurations. If you don't want to enable tracing for the plugin, you can skip this step.

In restified-endpoints-plugin directory, update the wrangler.toml file with the required configurations.

...
[vars]
OTEL_EXPORTER_OTLP_ENDPOINT = "https://gateway.otlp.hasura.io:443/v1/traces"
OTEL_EXPORTER_PAT = "<PAT>"

Replace <PAT> with the Personal Access Token (PAT) for the Hasura Cloud account. You can display this using the ddn auth print-pat command.

Step 7. Deploy the plugin

For your plugin to be reachable by your hosted supergraph, we'll need to deploy using Cloudflare Wrangler. The deploy command included in your plugin's package.json will do this automatically for you and return the hosted service's URL.

Note: Please also update the wrangler.toml with your cloud PAT for the tracing to work.

npm run deploy

This will deploy the plugin to Cloudflare Workers and return the URL of the hosted service. Next, update the .env.cloud file with the URL.

RESTIFIED_ENDPOINTS_URL="https://<your-deployed-plugin>.workers.dev"
M_AUTH_KEY="your-strong-m-auth-key"

Step 8. Create a new build

Create a new supergraph build on Hasura DDN to check your work in the cloud.

ddn supergraph build create

The engine will execute the plugin for each requests to the RESTified GraphQL endpoints you defined.