RESTified GraphQL Endpoints Plugin for Hasura DDN

Overview

This plugin for Hasura DDN (Distributed Data Network) allows you to add RESTified GraphQL endpoints to the DDN supergraph. It transforms GraphQL queries into REST-like endpoints, making it easier to integrate with systems that prefer REST APIs.

Features

• Transform GraphQL queries into REST-like endpoints
• Configurable endpoint mapping
• Authentication support
• Variable extraction from URL parameters, query strings, and request bodies
• OpenTelemetry integration for tracing

How it works

1. The plugin starts a server that listens for incoming requests.
2. When a request is received, it checks if it matches any configured RESTified endpoints.
3. If a match is found, the plugin:
   • Extracts variables from the request (URL parameters, query string, body)
   • Executes the corresponding GraphQL query with the extracted variables
   • Returns the GraphQL response as a REST-style JSON response

Configuration

Configure the plugin in src/config.ts:

• graphqlServer: GraphQL server settings (URL, headers)
• headers: Authentication headers
• restifiedEndpoints: Array of RESTified endpoint configurations

Example configuration:

export const Config = {
  graphqlServer: {
    url: "http://localhost:3000/graphql",
    headers: {
      additional: {
        "Content-Type": "application/json",
      },
      forward: ["X-Hasura-Role"],
    },
  },
  headers: {
    "hasura-m-auth": "zZkhKqFjqXR4g5MZCsJUZCcoPyZ",
  },
  restifiedEndpoints: [
    {
      path: "/v1/restified/:offset",
      method: "GET",
      query: `
        query MyQuery($limit: Int = 10, $offset: Int = 10) {
          Album(limit: $limit, offset: $offset) {
            Title
          }
        }
      `,
    },
    // Add more RESTified endpoints here
  ],
};

Development

Note: We are using Cloudflare wrangler for local development and deployment. However, you can use any other tool for the same. You will have to modify the files accordingly.

Local development

To run the plugin locally, you can use the following steps:

1. Install wrangler:

   npm install -g wrangler

2. Clone this repository:

   git clone https://github.com/your-org/engine-plugin-restified-endpoint.git
   cd engine-plugin-restified-endpoint

3. Install dependencies:

   npm install

4. Start the local development server:

   npm start

The above command will start a local server that listens for incoming requests. The server runs on port 8787 by default. The URL of the local server will be displayed in the terminal.

Cloud deployment

For cloud deployment, you can use the following steps in addition to the local development steps:

1. Create an account on Cloudflare.

2. Login to Cloudflare:

   wrangler login

3. Deploy to Cloudflare:

   npm run deploy

The above command should deploy the RESTified endpoints plugin (as a lambda) using Cloudflare workers. The URL of the deployed plugin will be displayed in the terminal.

Using the plugin in DDN

Update the metadata to add the plugin-related config (in global subgraph). Also, add the env vars for the URL of local dev and cloud deployment:

kind: LifecyclePluginHook
version: v1
definition:
  name: restified_endpoints
  url:
    valueFromEnv: RESTIFIED_ENDPOINTS_URL
  pre: route
  config:
    match: "/v1"
    request:
      headers:
        additional:
          hasura-m-auth:
            value: <your-secret-token>
        forward:
          - Authorization
          - X-Hasura-Role
      session: {}
      rawRequest:
        path: {}
        query: {}
        method: {}

Build DDN supergraph:

ddn supergraph build create

Note: For end-to-end tracing, you would have to update the wrangler.toml file to add the Hasura PAT in OTEL_EXPORTER_PAT var.

Adding new RESTified endpoints

To add new RESTified endpoints, update the restifiedEndpoints array in src/config.ts. For example:

restifiedEndpoints: [
  {
    path: "/v1/rest/users/:id",
    method: "GET",
    query: `
      query GetUser($id: ID!) {
        user(id: $id) {
          id
          name
          email
        }
      }
    `,
  },
  {
    path: "/v1/rest/posts",
    method: "GET",
    query: `
      mutation CreatePost($title: String!, $content: String!) {
        createPost(input: { title: $title, content: $content }) {
          id
          title
        }
      }
    `,
  },
];

After adding new endpoints, redeploy the plugin for the changes to take effect.

Limitations and Future Improvements

• The plugin currently supports only GET methods. Support for other HTTP methods will be added in the future.
• Currently, the plugin supports basic variable extraction. More complex scenarios might require additional implementation.
• OpenAPI Spec documentation generation is not yet implemented.
• Rate limiting is not currently supported within the plugin.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.