Tom Houlé

In this guide, we will walk through the process of setting up the Enterprise Platform to use GitLab directly for user authentication, without an intermediate service. We will log in through the Dashboard or Grafbase CLI using GitLab as the identity provider (IdP).

In technical terms, we are going to set up the OpenID Connect (OIDC) Authorization Code Grant flow to authenticate users and issue id tokens. The Dashboard is the client, the API is the resource server, and GitLab is the authorization server.

As a prerequisite, you will need a GitLab self hosted or hosted account, as well as a running deployment of the Enterprise Platform.

## Creating the GitLab application

On GitLab, navigate to "Applications" in user settings.

![GitLab applications page](/images/guides/gitlab-sso/1-create-application.png)

Click "create application".

![GitLab application creation UI](/images/guides/gitlab-sso/2-create-application.png)

Give your application a name. In the "Redirect URI" field, enter the URL of your Dashboard deployment with `/_auth/callback` as path.

Untick the "confidential" checkbox if your Dashboard deployment is not secured with TLS (`https://...`).

Select the "openid", "profile" and "email" scopes.

Click "save application". On the next screen, you will see the client ID and secret. Copy these values, we will need them in the next section. Then click "continue".

## Setting up the Dashboard

The Dashboard will need to be configured to use GitLab as the identity provider (IdP). This can be done by setting the following environment variables:

- `OIDC_PROVIDER_TYPE`: `generic`. Enables generic OIDC authentication mode.
- Set `OIDC_ISSUER` to the URL of your GitLab instance, or "https://gitlab.com" if you are using the public instance.
- `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET`: the client ID and secret you obtained in the previous section for the GitLab application you created.
- `OIDC_SCOPES`: `"profile email"` requests the scopes the Grafbase Enterprise platform needs to function properly.

Before navigating to the Dashboard, we have to set up the Grafbase API deployment to accept the JWTs we will obtain from GitLab.

## Setting up the API

The API deployment only needs the `GRAFBASE_OIDC_ISSUER` environment variable to be set. Use the same value we used in the previous section for `OIDC_ISSUER`. It will discover the JWKS to validate the incoming JWTs with the standard OIDC discovery mechanisms.

## Logging in

Now (re)start the Dashboard and API with the new environment variables. Navigate to the Dashboard, and you should be redirected to the GitLab login screen. Once you log in there, you should be redirected back to the Dashboard and fully logged in.

## Automatic provisioning of organization memberships using the groups claim

If you requested the `openid` scope in `OIDC_SCOPES` in the Dashboard, the JWTs returned by GitLab will contain the `groups_direct` claim with the groups the logged in user is a part of.

If you set the "OIDC issuer" and "OIDC group name" settings in the "Security" tab of organization settings in the Dashboard to values that appear in that claim, the API will automatically add new users to your organization the first time it encounters them, if one of the groups in the `groups` claim in their JWT matches the "OIDC group name" setting. For security reasons, the "OIDC issuer" setting must also match the `iss` (issuer) claim in the JWT.

![OIDC organization settings](/images/guides/gitlab-sso/3-jit-provisioning.png)

## Conclusion

You now have a fully functional Grafbase Enterprise Platform deployment with GitLab authentication and automatic organization membership provisioning, without any other third party service involved.

Learn how to set up the Enterprise Platform to use GitLab directly for user authentication

Setting up GitLab Single Sign-On with the Enterprise Platform

In this guide, we will walk through the process of setting up the Enterprise Platform to use Okta directly for user authentication, without an intermediate service. We will log in through the Dashboard or Grafbase CLI using Okta as the identity provider (IdP).

In technical terms, we are going to set up the OpenID Connect (OIDC) Authorization Code Grant flow to authenticate users and issue id tokens. The Dashboard is the client, the API is the resource server, and Okta is the authorization server.

As a prerequisite, you will need an Okta account with the necessary permissions to create applications, as well as a running deployment of the Enterprise Platform.

## Creating the Okta application

Log in to your Okta account, and go to the Admin interface.

![Go to admin](/images/guides/okta-sso/1-go-to-admin.png)

Then on the left, find the "Applications" section, and navigate there.

![Go to Applications](/images/guides/okta-sso/2-go-to-applications.png)

On the applications screen, click "Create App Integration".

![Applications screen](/images/guides/okta-sso/3-applications-screen.png)

In the creation screen, select "OIDC — OpenId Connect", and "Web Application".

![Create application](/images/guides/okta-sso/4-create-application.png)

Then give your integration a name, for example "Grafbase Enterprise Platform". Select the "Refresh token" box in "Grant Type", and enter the root URL of your deployment of the Grafbase Dashboard, with `/_auth/callback` as the path in "Sign-in redirect URIs". The sign-out URI is not as important — you can set it to the root of your Dashboard deployment for example.

![Create application](/images/guides/okta-sso/5-create-application.png)

In "Assignments", check the box that matches your internal policies, otherwise "Allow everyone in the organization to access". Then save.

![Create application](/images/guides/okta-sso/6-create-application.png)

You are now on the application screen. You can see a client ID and a client secret. Take note of these values, we will need them later. Then navigate to the "Sign On" tab.

![Application client id and secret](/images/guides/okta-sso/7-application-client-id-and-secret.png)

In the "Sign On" tab, we will configure the groups claim inside the "OpenID Connect Token" section. Click "Edit".

![OIDC configuration](/images/guides/okta-sso/8-oidc-configuration.png)

There, add the groups you want the Enterprise Platform to be aware of (to provision organization and team memberships), or "matches regex", and ".*" to include all groups.

![Add groups claim](/images/guides/okta-sso/9-add-groups-claim.png)

## Setting up the Dashboard

The Dashboard will need to be configured to use Okta as the identity provider (IdP). This can be done by setting the following environment variables:

- `OIDC_PROVIDER_TYPE`: `generic`. Enables generic OIDC authentication mode.
- Set `OIDC_ISSUER` to the URL of your Okta instance or authorization server, for example "https://trial-4034757.okta.com/".
- `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET`: the client ID and secret you obtained in the previous section for the Okta application you created.
- `OIDC_SCOPES`: `"openid profile email groups offline_access"` requests the scopes the Grafbase Enterprise platform needs to function properly.

Before navigating to the Dashboard, we have to set up the Grafbase API deployment to accept the JWTs we will obtain from Okta.

## Setting up the API

The API deployment only needs the `GRAFBASE_OIDC_ISSUER` environment variable to be set. It will discover the JWKS to validate the incoming JWTs with the standard OIDC discovery mechanisms.

## Automatic provisioning of organization memberships using the groups claim

If you requested the `groups` scope in `OIDC_SCOPES` in the Dashboard, the JWTs returned by Okta will contain the `groups` claim with the groups the logged in user is a part of.

If you set the "OIDC issuer" and "OIDC group name" settings in the "Security" tab of organization settings in the Dashboard to values that appear in that claim, the API will automatically add new users to your organization the first time it encounters them, if one of the groups in the `groups` claim in their JWT matches the "OIDC group name" setting. For security reasons, the "OIDC issuer" setting must also match the `iss` (issuer) claim in the JWT.

![OIDC organization settings](/images/guides/okta-sso/10-jit-provisioning.png)

## Conclusion

You now have a fully functional Grafbase Enterprise Platform deployment with Okta authentication and automatic organization membership provisioning, without any other third party service involved.

Learn how to set up the Enterprise Platform to use Okta directly for user authentication

Setting up Okta Single Sign-On with the Enterprise Platform

Julius de Bruijn

Hooks is a [Grafbase Gateway](/docs/gateway/installation) [extension](/extensions) type, which allows you to hook into every incoming request before the gateway processes it, and every outgoing response right before you send it back to the client. Hooks help you generate custom headers, modify existing headers, and implement an audit log based on the events that occur during the request processing pipeline.

In comparison to other gateway extension types, a hooks extension is always custom for your gateway deployment.

## Hooks Source Code Structure

You implement hooks as Rust functions that compile into a WebAssembly component and an extension manifest file. The Grafbase Gateway engine loads the files. There are two hooks: [`on-request`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html#tymethod.on_request), which the system calls immediately after the gateway receives the request, and [`on-response`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html#tymethod.on_response), which the system calls immediately before you send the response back to the client.

Start by downloading the [Grafbase CLI](/docs/cli/installation), [Grafbase Gateway](/docs/gateway/installation), and installing the [Rust toolchain](https://www.rust-lang.org/tools/install). For good developer experience, we recommend installing the [rust-analyzer](https://rust-analyzer.github.io/) and a good programmer editor, such as [Zed](https://zed.dev/), [VSCode](https://code.visualstudio.com/), [NeoVim](https://neovim.io/), or [Emacs](https://www.gnu.org/software/emacs/).

Initialize a new hooks extension with the Grafbase CLI:

```bash
grafbase extension init --type hooks my-hooks
```

The project is structured as follows:

```bash
my-hooks/
├── Cargo.toml
├── extension.toml
├── src
│   └── lib.rs
└── tests
    └── integration_tests.rs
```

- `Cargo.toml`: The project manifest file that defines the project dependencies and configuration.
- `extension.toml`: The extension configuration file that defines the extension metadata, permissions, and static configuration.
- `src/lib.rs`: The main Rust file that implements the hooks.
- `tests/integration_tests.rs`: The integration tests file that tests the hooks.

You can build the extension by running `grafbase extension build`, and run the tests by running `cargo test`.

## Implementing Hooks

The template in `src/lib.rs` provides a starting point for implementing hooks. You can modify this file to implement your own hooks.

The simplest possible hooks implementation looks like this:

```rust
use grafbase_sdk::{
    HooksExtension,
    types::{Configuration, Error, ErrorResponse, GatewayHeaders},
    host_io::event_queue::EventQueue,
    host_io::http::{Method, StatusCode},
};

#[derive(HooksExtension)]
struct MyHooks;

impl HooksExtension for MyHooks {
    fn new(config: Configuration) -> Result<Self, Error> {
        Ok(Self)
    }

    fn on_request(&mut self, url: &str, method: Method, headers: &mut GatewayHeaders) -> Result<(), ErrorResponse> {
        Ok(())
    }

    fn on_response(
        &mut self,
        status: StatusCode,
        headers: &mut GatewayHeaders,
        event_queue: EventQueue,
    ) -> Result<(), String> {
        Ok(())
    }
}
```

The use block in the beginning imports types and modules we use in the extension:

```rust
use grafbase_sdk::{
    HooksExtension,
    types::{Configuration, Error, ErrorResponse, GatewayHeaders},
    host_io::event_queue::EventQueue,
    host_io::http::{Method, StatusCode},
};
```

After the imports, we define a struct `MyHooks` with a proc macro to derive the `HooksExtension`. The compiler will generate the needed initialization code to the struct that derives the macro attribute.

```rust
#[derive(HooksExtension)]
struct MyHooks;
```

You can keep state in the struct by adding fields to it, and access them from the hook functions through the `&mut self` reference. Keep in mind that there will be multiple instances of the struct running in parallel, so each instance will have its own state.

In the next part we initialize the [`HooksExtension`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html) trait for the `MyHooks` struct. A trait is an interface, and by adding the [`HooksExtension`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/derive.HooksExtension.html) proc macro attribute to our struct, the compiler expects it to implement the [`HooksExtension`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html) trait:

```rust
impl HooksExtension for MyHooks {
    ...
}
```

The extension must implement the following function and methods. The first is [`new`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html#tymethod.new), which the system calls every time the extension pool reaches capacity and needs to initialize a new instance to serve a request:

```rust
fn new(config: Configuration) -> Result<Self, Error> {
    Ok(Self)
}
```

The configuration struct [provides access](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/types/struct.Configuration.html#method.deserialize) to the extension's configuration. In our case, if you build the extension to `/path/to/my-hooks/build`, and our gateway configuration in `grafbase.toml` defines the following:

```toml
[extensions.my-hooks]
path = "/path/to/my-hooks/build"

[extensions.my-hooks.config]
my_key = "my_value"
```

We can define a struct to hold the configuration values:

```rust
#[derive(HooksExtension)]
struct MyHooks {
    config: Config,
}

#[derive(serde::Deserialize)]
struct Config {
    my_key: String,
}

impl HooksExtension for MyHooks {
    fn new(config: Configuration) -> Result<Self, Error> {
        let config = config.deserialize()?;

        Ok(Self { config })
    }
}
```

Now the configuration values are available for every subsequent hook calls.

The gateway calls the [`on_request`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html#tymethod.on_request) method for every incoming request:

```rust
fn on_request(
    &mut self,
    url: &str,
    method: Method,
    headers: &mut GatewayHeaders
) -> Result<(), ErrorResponse> {
    Ok(())
}
```

Here you get the following arguments:

- `url`: The URL of the request.
- `method`: The HTTP method of the request.
- `headers`: A mutable reference to the [headers](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/types/struct.GatewayHeaders.html) of the request.

If the hook returns `Ok(())`, the request continues execution. Consider using the [Authentication](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.AuthenticationExtension.html) extension for more advanced authentication facilities, and consider the on-request hook for request modification and event sending.

The gateway calls the [`on_response`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html#tymethod.on_response) hook for every response the gateway sends.

```rust
fn on_response(
    &mut self,
    status: StatusCode,
    headers: &mut GatewayHeaders,
    event_queue: EventQueue,
) -> Result<(), String> {
    Ok(())
}
```

Here you get the following arguments:

- `status`: The [status code](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/http/struct.StatusCode.html) of the response.
- `headers`: A mutable reference to the [headers](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/types/struct.GatewayHeaders.html) of the response.
- `event_queue`: A [queue of events](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/event_queue/struct.EventQueue.html) that flow through the request processing.

The response hooks is a good point to modify the response headers if needed, and to store audit logs per request.

## Event Queue

The gateway sends a set of standard events to the [event queue](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/event_queue/struct.EventQueue.html), which the system creates for every request. You must enable the event types separately in the hooks project `extension.toml` file:

```toml
[hooks]
events = "*"
```

The value of `events` is a comma-separated list of event types to enable, or a wildcard (`"*"`) to enable all event types. The available event types are:

- `operation`: The system sends [an operation event](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/event_queue/struct.ExecutedOperation.html) when it executes a GraphQL operation.
- `subgraph_request`: The system sends [a subgraph event](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/event_queue/struct.ExecutedSubgraphRequest.html) whenever a subgraph request completes. If the system retries the request, the event holds the response data for every try.
- `http_request`: The system sends [an http event](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/event_queue/struct.ExecutedHttpRequest.html) whenever the gateway sends an HTTP response.
- `extension`: Any extension can send [custom events](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/event_queue/struct.ExtensionEvent.html). The event has a custom name, and serialized data.

You can define your own event type in the hooks extension:

```rust
#[derive(serde::Serialize, serde::Deserialize)]
struct CustomEvent {
    correlation_id: String,
}

impl HooksExtension for MyHooks {
    fn on_request(
        &mut self,
        url: &str,
        method: Method,
        headers: &mut GatewayHeaders
    ) -> Result<(), ErrorResponse> {
        let event = CustomEvent {
            correlation_id: id_generator::generate_correlation_id(),
        };

        grafbase_sdk::host_io::event_queue::send("special_event", event)?;

        Ok(())
    }
}
```

And then aggregate the events in the [`on_response`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html#tymethod.on_response) hook:

```rust
impl HooksExtension for MyHooks {
    fn on_response(
        &mut self,
        status: StatusCode,
        headers: &mut GatewayHeaders,
        event_queue: EventQueue,
    ) -> Result<(), String> {
        while let Some(event) = event_queue.pop() {
            match event {
                Event::Operation(op) => {
                    // handle operation events
                }
                Event::Subgraph(req) => {
                    // handle subgraph events
                }
                Event::Http(resp) => {
                    // handle http events
                }
                Event::Extension(event) => {
                    if event.event_name() == "special_event" && event.extension_name() == "my-hooks" {
                        let event: CustomEvent = event.deserialize()
                            .map_err(|e| format!("Failed to deserialize event: {e}"))?;

                        // handle the special event from on_response
                    } else {
                        // handle or ignore other extension events
                    }
                }
            }
        }

        Ok(())
    }
}
```

The Grafbase SDK crate provides two kinds of loggers: [`FileLogger`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/logger/struct.FileLogger.html) to log custom data to a file with a possible rolling mechanism. Or if using the [log crate](https://docs.rs/log/latest/log/), you can send log events to the gateway system logger. A file logger is useful if you must have access logs in a separate place outside of the system logs. Create one in the extension initialization and store the instance to the `MyHooks` struct:

```rust
impl HooksExtension for MyHooks {
    fn new(config: Configuration) -> Result<Self, Error> {
        let config = config.deserialize()?;
        let logger = FileLogger::new("/path/to/access.log", None)?;

        Ok(Self { config, logger })
    }
}
```

Then in the [`on_response`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/trait.HooksExtension.html#tymethod.on_response) method, you can send any structure deriving serde's `Deserialize` trait. The logger provides a convenient [`log_json`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/logger/struct.FileLogger.html#method.log_json) method to store JSON data, but also a [`log`](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/host_io/logger/struct.FileLogger.html#method.log) method to store any serialized data if you prefer storing logs in some other format:

```rust
self.logger.log_json(my_data)?;
```

Alternatively, you can use the [log crate](https://docs.rs/log/latest/log/) to push the logs to the gateway's system logger:

```rust
log::info!("Received response: {:?}", my_data);
log::debug!(foo = "bar", kekw = 2; "some message");
```

You can set the log levels from the [gateway log level argument](/docs/gateway/arguments#log-level). To enable info logs from the gateway and extensions:

```rust
grafbase-gateway --log=info
```

To enable debug logs from the extensions, info logs from the gateway:

```rust
grafbase-gateway --log=extension=debug,info
```

Keep in mind, if you configure a custom OpenTelemetry exporter in the Grafbase gateway, the system will include the logs passed through the log macros in the data sent to OpenTelemetry.

## Deployment

A typical deployment with the Grafbase Gateway and the hooks extension should contain the following files:

```bash
.
├── build
│   ├── extension.wasm
│   └── manifest.json
└── grafbase.toml
```

The build directory contains the `extension.wasm` and `manifest.json` files, which the `grafbase extension build` command generates. The `grafbase.toml` should provide the needed configuration to load the extension:

```toml
[extensions.my-hooks]
path = "./build"

[extensions.my-hooks.config]
my_key = "my_value"
```

You can base your own custom docker image on the [Grafbase Gateway Docker image](https://ghcr.io/grafbase/gateway), extending it to build and copy the extension and configuration files.

Extend your gateway with custom hooks using Rust and Grafbase SDK.

Get Started

Learn how to implement Grafbase Gateway Hooks in Rust using Grafbase SDK

Implementing Gateway Hooks

GraphQL typically requires clients to construct and send queries as part of POST requests. This works well for GraphQL-aware clients but can be challenging for systems that prefer simpler REST-like interfaces. This guide demonstrates how to expose specific GraphQL operations via GET requests using trusted document IDs, making your GraphQL API accessible to a wider range of clients.

## Prerequisites

- A Grafbase account and graph
- [Grafbase CLI](/docs/cli/installation) installed
- Basic understanding of [Trusted Documents](/docs/gateway/security/trusted-documents)

## Overview

Trusted Documents allow you to register an allow-list of GraphQL operations. Once registered, clients can execute these operations by referencing their document IDs rather than sending the full query text. This approach offers two significant benefits:

1. **Simplified client implementation**: Clients can make simple GET requests without constructing GraphQL queries
2. **Enhanced security**: Only pre-registered operations can be executed

While Trusted Documents are commonly used with POST requests, they also work with GET requests, following the [GraphQL over HTTP specification](https://github.com/graphql/graphql-over-http). This allows clients to execute GraphQL operations using familiar REST-like patterns.

## Step 1: Create Your GraphQL Operations

First, define the GraphQL operations you want to expose. For this example, we'll create two operations - a query and a mutation:

```graphql
# get-product.graphql
query GetProduct($id: ID!) {
  product(id: $id) {
    id
    name
    price
    description
  }
}

# create-order.graphql
mutation CreateOrder($productId: ID!, $quantity: Int!) {
  createOrder(input: { productId: $productId, quantity: $quantity }) {
    id
    status
    total
  }
}
```

## Step 2: Generate a Trusted Documents Manifest

The next step is to generate a manifest file for these operations. You can use various client tools for this purpose, as documented in the [Trusted Documents](/docs/gateway/security/trusted-documents) page.

This creates a manifest.json file containing your operations and their document IDs.

You can also create a `manifest.json` file that is just one object where the keys are the document ids, and the values are the corresponding GraphQL queries.

## Step 3: Upload the Trusted Documents Manifest

Upload the manifest to your Grafbase project:

```bash
grafbase trust my-account/my-graph@main --manifest manifest.json --client-name api-gateway
```

## Step 4: Configure Your Gateway

Enable trusted documents in your `grafbase.toml` configuration:

```toml
[trusted_documents]
enabled = true
enforced = false # optional, only set this if you want to adopt trusted documents whole-sale
```

`enabled` will only cause the Gateway to accept trusted document queries, not to enforce their usage.

## Step 5: Query with GET Requests

Now you can execute your GraphQL operations using simple GET requests with document IDs:

### Query Example

```bash
curl -X GET 'https://myapi.grafbase.app/graphql?document_id=<get-product-doc-id>&variables={"id":"prod-123"}' \
  -H 'x-grafbase-client-name: api-gateway'
```

### Mutation Example

While mutations are typically performed with POST requests, they can also work with GET requests when using document IDs:

```bash
curl -X GET 'https://myapi.grafbase.app/graphql?document_id=<create-order-doc-id>&variables={"productId":"prod-123","quantity":2}' \
  -H 'x-grafbase-client-name: api-gateway'
```

## Troubleshooting

Common issues when working with trusted document IDs and GET requests:

- **404 Not Found**: Ensure the document ID exists in your trusted documents manifest
- **Client name mismatch**: Verify the `x-grafbase-client-name` header matches the name used when uploading the manifest
- **Variable format errors**: Ensure variables are properly JSON-encoded in the URL. Note that the usage of variables is optional, queries that are always the same do not need them.
- **URL length limitations**: For operations with many variables, consider using POST requests instead of GET

## Conclusion

Using trusted document IDs with GET requests provides a bridge between GraphQL and REST-like APIs. This approach allows you to leverage GraphQL's power while exposing a simple interface for clients that prefer traditional HTTP methods. By registering only the operations you want to expose, you maintain control over your API's surface area while providing an accessible interface for all your clients.

## Examples in Different Environments

### JavaScript Fetch API

```javascript
// Using fetch to call a trusted document
const fetchProduct = async (productId) => {
  const response = await fetch(
    `https://myapi.grafbase.app/graphql?document_id=abcdef123456&variables={"id":"${productId}"}`,
    {
      method: 'GET',
      headers: {
        'x-grafbase-client-name': 'api-gateway'
      }
    }
  );
  return response.json();
};
```

### Python Requests

```python
import requests
import json

# Using requests to call a trusted document
def fetch_product(product_id):
    variables = json.dumps({"id": product_id})
    response = requests.get(
        f"https://myapi.grafbase.app/graphql?document_id=abcdef123456&variables={variables}",
        headers={"x-grafbase-client-name": "api-gateway"}
    )
    return response.json()
```

### Curl with URL-encoded Variables

For more complex variables, you might need to URL-encode the JSON:

```bash
# URL-encode the variables JSON
VARIABLES=$(python -c "import urllib.parse; print(urllib.parse.quote('{\"id\":\"prod-123\"}'))")

# Make the request with encoded variables
curl -X GET "https://myapi.grafbase.app/graphql?document_id=abcdef123456&variables=$VARIABLES" \
  -H 'x-grafbase-client-name: api-gateway'
```

## Integrating with Backend Systems

### Webhooks

Trusted document IDs are particularly useful for webhook integrations. When a third-party service needs to trigger an action in your system:

1. Create a specific mutation for the webhook action
2. Register it as a trusted document
3. Provide the webhook URL with the document ID

```
https://gateway.myapp.dev/graphql?document_id=webhook123&variables={"payload":"..."}
```

### Scheduled Tasks

For cron jobs or scheduled tasks that need to perform specific operations:

```bash
# Crontab entry that runs daily at midnight
0 0 * * * curl -X GET 'https://myapi.grafbase.app/graphql?document_id=dailyReport&variables={"date":"'$(date +'%Y-%m-%d')'"}'  -H 'x-grafbase-client-name: api-gateway' > /var/log/daily-report.log
```

## Performance Optimization

Using trusted document IDs with GET requests allows for effective HTTP caching:

```bash
# Request that leverages HTTP caching
curl -X GET 'https://myapi.grafbase.app/graphql?document_id=getPopularProducts&variables={}' \
  -H 'x-grafbase-client-name: api-gateway' \
  -H 'Cache-Control: max-age=300'
```

Learn how to simplify GraphQL API access for non-GraphQL clients with trusted document IDs.

Learn how to expose GraphQL APIs to non-GraphQL clients using trusted document IDs and simple GET requests

Exposing GraphQL APIs with Trusted Document IDs and GET Requests

## Prerequisites

- Docker installed for Docker deployment
- Kubernetes cluster and kubectl for Kubernetes deployment
- Helm installed for Kubernetes deployment
- Grafbase Access Token (if using schema registry, or dashboard analytics)
- Grafbase graph ref (if using schema registry), or a local federated schema file
- Locally built or downloaded extensions (from `grafbase extension install`) and a configuration file (`grafbase.toml`) with an extensions section

## Understanding Grafbase Gateway with Extensions

Grafbase Gateway is a GraphQL federation gateway that can be extended with custom functionality through extensions. Extensions allow you to add custom resolvers, authentication logic, and more to your GraphQL API.

Extensions are implemented as WebAssembly components that are loaded by the gateway at runtime. The extensions are installed in a directory named `grafbase_extensions`, which must be available to the gateway when it starts. Alternatively, you can define the extension to be in a specific path in `grafbase.toml` under the `extensions` section. This path must have a valid extension WebAssembly component, and the manifest file.

To set up a Grafbase Gateway with extensions, you need:

1. The `grafbase-gateway` binary
2. A `grafbase_extensions` directory containing installed extensions (install them with `grafbase extension install`)
3. A configuration file (typically `grafbase.toml`)
4. Either environment variables to fetch the schema from Grafbase's registry, or a local federated GraphQL schema file

## Docker Deployment

### Using Schema Registry with Docker

This approach uses the Schema Registry to fetch the graph schema based on a Graph Reference and Access Token. This method polls for changes to the schema automatically every ten seconds, and restarts the gateway with changes.

#### Step 1: Create a Dockerfile

Create a `Dockerfile` in the root of your project.

```dockerfile
FROM ghcr.io/grafbase/gateway:0.38.0 # or later version!

# Create directories
WORKDIR /app

# Copy the configuration file
COPY grafbase.toml /app/grafbase.toml

# Copy the extensions directory if you have custom extensions
COPY grafbase_extensions /app/grafbase_extensions

# Set default command
CMD ["--config", "/app/grafbase.toml"]
```

#### Step 2: Create a Grafbase Configuration File

Create a `grafbase.toml` file in the root of your project.

```toml
[graph]
introspection = true

[network]
listen_address = "0.0.0.0:5000"

[extensions]
rest = "0.4"
```

#### Step 3: Install Extensions

Before building the Docker image, install the extensions:

```bash
grafbase extension install
```

This will create or update the `grafbase_extensions` directory with the specified extensions.

#### Step 4: Create a Subgraph per Extension Instructions

Before deploying the gateway, create all subgraphs as needed, and publish them to the Schema Registry. For this simple example, we will create a subgraph that fetches country names from a public REST API.

Create a `subgraph.graphql` in the root of your project:

```graphql
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
  @link(url: "https://grafbase.com/extensions/rest/0.4.1", import: ["@restEndpoint", "@rest"])

@restEndpoint(
  name: "restCountries",
  baseURL: "https://restcountries.com/v3.1"
)

type Country {
  name: String!
}

type Query {
  listAllCountries: [Country!]! @rest(
    method: GET
    endpoint: "restCountries"
    path: "/all"
    selection: "[.[] | { name: .name.official }]"
  )
}
```

Publish the subgraph to the Schema Registry:

```bash
grafbase publish \
    --name restCountries \
    your-org/your-graph@branch \
    -m initx \
    --virtual \
    --schema subgraph.graphql
```

#### Step 5: Create a Docker Compose Configuration

Create a `compose.yml` in the root of your project:

```yaml
services:
  grafbase:
    build: .
    restart: always
    environment:
      GRAFBASE_GRAPH_REF: 'your-graph@branch'
      GRAFBASE_ACCESS_TOKEN: 'your-access-token'
    ports:
      - '5000:5000'
```

The access token should be created in the Grafbase dashboard, and scoped to have access to the graph.

#### Step 5: Build and Run

```bash
docker-compose up -d
```

### Using Local GraphQL Schema with Docker

This approach uses a local federated GraphQL schema file instead of fetching it from the Schema Registry. This step requires you to manually fetch the federated schema when it is updated. You can replace the schema file in the running container without restarting the gateway. The gateway will automatically reload the schema when it changes.

#### Step 1: Create a Dockerfile

Add the following content to the `compose.yml` file:

```dockerfile
FROM ghcr.io/grafbase/gateway:0.38.0 # or later

# Create directories
WORKDIR /app

# Copy the configuration file
COPY grafbase.toml /app/grafbase.toml

# Copy the federated schema
COPY federated-graph.graphql /app/federated-graph.graphql

# Copy the extensions directory
COPY grafbase_extensions /app/grafbase_extensions

# Set default command
CMD ["--config", "/app/grafbase.toml", "--schema", "/app/federated-graph.graphql"]
```

#### Step 2: Create a Grafbase Configuration File

Same as the previous example.

#### Step 3: Install Extensions

Same as the previous example.

#### Step 4: Create an Publish Subgraph

Same as the previous example.

#### Step 5: Fetch the Federated Schema

After successfully publishing a subgraph, fetch the federated schema using the following command:

```bash
grafbase schema your-org/your-graph@branch > federated-graph.graphql
```

#### Step 6: Create a Docker-compose.yml File

```yaml
version: '3'
services:
  grafbase:
    build: .
    restart: always
    ports:
      - '5000:5000'
    # keep the environment variables if you want dashboard
    # analytics. remove, if you want to run the gateway
    # totally air-gapped
    environment:
      GRAFBASE_GRAPH_REF: 'your-graph@branch'
      GRAFBASE_ACCESS_TOKEN: 'your-access-token'
    volumes:
      # Mount the schema file as a volume for easy updates
      - ./federated-graph.graphql:/app/federated-graph.graphql
```

#### Step 7: Build and Run

```bash
docker-compose up -d
```

## Kubernetes Deployment

### Using Schema Registry with Kubernetes

This method uses Helm to deploy the Grafbase Gateway that fetches the schema from the Schema Registry.

#### Step 1: Create a Custom Dockerfile Following the Previous example

See the [step 1 from the Docker example](/guides/deploying-grafbase-gateway-with-extensions#step-1-create-a-dockerfile) to create a custom Dockerfile with extensions. Publish this Docker image to a repository which is available for Helm. It is a good practice to tag the image with the same version number the Grafbase Gateway container image uses.

#### Step 2: Create a Custom Values File for Helm

Create a custom `values.yaml` file for Helm:

```yaml
replicaCount: 2

image:
  repository: path/to/custom-gateway-repository
  tag: 0.38.0 # or later version
  pullPolicy: Always

service:
  type: ClusterIP
  port: 80
  targetPort: 5000

gateway:
  externalSchema: true
  externalConfig: false
  config: |
    [graph]
    introspection = true

    [network]
    listen_address = "0.0.0.0:5000"

    [extensions]
    rest = "0.4"

secrets:
  enabled: true
  values:
    GRAFBASE_GRAPH_REF: "your-graph@branch"
    GRAFBASE_ACCESS_TOKEN: "your-access-token"
```

#### Step 3: Install the Helm Chart

```bash
helm install grafbase-gateway oci://ghcr.io/grafbase/helm-charts/gateway --version 0.2.5 -f values.yaml
```

### Using Local GraphQL Schema with Kubernetes

This method uses a local federated GraphQL schema file baked into the docker image.

#### Step 1: Create a Custom Dockerfile Following the Previous example

See the [step 1 from the Docker example](/guides/deploying-grafbase-gateway-with-extensions#step-1-create-a-dockerfile) to create a custom Dockerfile with extensions. Publish this Docker image to a repository which is available for Helm. It is a good practice to tag the image with the same version number the Grafbase Gateway container image uses and your own versioning scheme for the schema.

#### Step 2: Create a Custom Values File for Helm

Create a custom `values.yaml` file for Helm:

```yaml
replicaCount: 2

image:
  repository: path/to/custom-gateway-repository
  tag: 0.38.0 # or later version
  pullPolicy: Always

service:
  type: ClusterIP
  port: 80
  targetPort: 5000

gateway:
  externalSchema: true
  externalConfig: false
  config: |
    [graph]
    introspection = true

    [network]
    listen_address = "0.0.0.0:5000"

    [extensions]
    rest = "0.4"

  args:
    - --config
    - /etc/grafbase/config/grafbase.toml
    - --schema
    - /app/federated-graph.graphql

volumes:
  - name: configuration
    configMap:
      name: grafbase-gateway-configuration
volumeMounts:
  - name: configuration
    mountPath: /etc/grafbase/config
```

#### Step 3: Install the Helm Chart

```bash
helm install grafbase-gateway oci://ghcr.io/grafbase/helm-charts/gateway --version 0.2.5 -f values.yaml
```

## Additional Configuration

### Customizing Extensions

You can customize extensions by modifying your `grafbase.toml` file. For example, to configure the JWT extension:

```toml
[extensions.jwt]
version = "1.0"

[extensions.jwt.config]
jwks.url = "https://example.com/.well-known/jwks.json"
jwks.issuer = "example.com"
jwks.audience = "my-project"
jwks.poll_interval = 60

[extensions.jwt.config.header]
name = "Authorization"
value_prefix = "Bearer "
```

### Health Checks

Configure health checks in your `grafbase.toml`:

```toml
[health]
enabled = true
listen = "0.0.0.0:9668"
path = "/health"
```

### Advanced Telemetry

For production environments, you might want to set up telemetry:

```toml
[telemetry]
service_name = "my-federated-graph"

[telemetry.tracing]
enabled = true
sampling = 1

[telemetry.tracing.exporters.otlp]
enabled = true
endpoint = "http://my-otel-collector:4317"
protocol = "grpc"
timeout = 5
```

## Conclusion

This guide has demonstrated how to deploy Grafbase Gateway with extensions in both Docker and Kubernetes environments. By following these instructions, you can set up a flexible and extensible GraphQL federation gateway that meets your specific needs, whether you're using Grafbase's Schema Registry or a local schema file.

Deploy your Grafbase Gateway with Extensions to Docker, Kubernetes, or any other platform.

Learn how to deploy Grafbase Gateway with Extensions to Docker, Kubernetes, or any other platform.

Deploying Grafbase Gateway with Extensions

GraphQL Federation combines the best features of monolith APIs and microservices into one API architecture. It gives you a single endpoint for all your services while keeping a distributed architecture. Federation delivers decoupled design, schema composition, and efficient data querying.

GraphQL Federation helps you combine multiple APIs into a single, federated graph. This federated graph allows clients to interact with your APIs through a single request. A client sends a request to the federated GraphQL API's single entry point - the Grafbase Gateway. The gateway orchestrates and distributes the request across your APIs and returns a unified response. For a client, querying the gateway feels identical to querying any GraphQL server.

Build three simple subgraphs: `accounts`, `products`, and `reviews`. Experience GraphQL Federation, publish subgraphs to a federated graph, join data between subgraphs, and add different federation directives to the schema.

## Prerequisites

Create a new account on the [Grafbase dashboard](/dashboard), and install the [Grafbase CLI](/docs/cli/installation) and [Grafbase Gateway](/docs/gateway/installation) before you start.

## Accounts Subgraph

Start by creating the `accounts` subgraph with Node.js and GraphQL Yoga. First, create a new directory and initialize a new Node.js project.

```bash
mkdir accounts && cd accounts
npm init -y
npm install graphql-yoga @apollo/subgraph graphql
```

Next, create a new file `index.js` and add the following code:

```javascript
import { createSchema, createYoga } from "graphql-yoga";
import { createServer } from "http";

const users = [
  {
    id: "1",
    email: "john@example.com",
    username: "john_doe",
  },
  {
    id: "2",
    email: "bob@example.com",
    username: "bob_dole",
  },
];

const schema = createSchema({
  typeDefs: /* GraphQL */ `
    type Query {
      users: [User!]!
    }

    type User {
      id: ID!
      email: String!
      username: String!
    }
  `,
  resolvers: {
    Query: {
      users: () => users,
    },
  },
});

const yoga = createYoga({ schema });
const server = createServer(yoga);

server.listen(4000, () => {
  console.log("🚀 Server ready at http://localhost:4000/graphql");
});
```

Launch the server by running `node index.js`. Access the GraphQL playground at [http://localhost:4000/graphql](http://localhost:4000/graphql).

The `accounts` subgraph is simple and not yet ready for Federation. A single query `users` returns all users in the subgraph:

```graphql
query {
  users {
    id
    email
    username
  }
}
```

Which returns:

```json
{
  "data": {
    "me": {
      "id": "1",
      "email": "john@example.com",
      "username": "john_doe"
    }
  }
}
```

While the Grafbase Gateway typically federates multiple subgraphs, you can create a configuration for a single subgraph and publish it to the schema registry. Use the [grafbase dev](/docs/cli/commands/dev) command to start the local dev server. Add this to the `grafbase.toml` configuration file:

```toml
[subgraphs.accounts]
introspection_url = "http://localhost:4000/graphql"
```

Start the Grafbase dev server:

```bash
grafbase dev
```

Open Explorer and query the federated graph at `http://127.0.0.1:5000`.

### Federating the Account subgraph with the @key Directive

Define an identifier for a type to be part of federation. The `User` type has the `id` field as the identifier. Add the [`@key` directive](/docs/federation/graphql-directives#key) to the `User` type:

```graphql
type Query {
  me: User
}

type User @key(fields: "id") {
  id: ID!
  email: String!
  username: String!
}
```

Modify the Yoga server to accommodate federation. Use the `@apollo/subgraph` package to create a federated schema, parse the schema with `graphql` library and add the edge `__resolveReference` to the user type. The [`@key` directive](/docs/federation/graphql-directives#key) identifies `User` as an entity with the `id` field. Use the same `User` type in multiple subgraphs, with each subgraph resolving the `User` type by its `id`. The `__resolveReference` function resolves the user by the `id` field, returning the user object. It is called when the gateway needs to resolve a user reference.

```javascript
import { buildSubgraphSchema } from "@apollo/subgraph";
import { parse } from "graphql";
import { createYoga } from "graphql-yoga";
import { createServer } from "http";

const users = [
  {
    id: "1",
    email: "john@example.com",
    username: "john_doe",
  },
  {
    id: "2",
    email: "bob@example.com",
    username: "bob_dole",
  },
];

const typeDefs = parse(/* GraphQL */ `
  type Query {
    users: [User!]!
  }

  type User @key(fields: "id") {
    id: ID!
    email: String!
    username: String!
  }
`);

const resolvers = {
  Query: {
    users: () => users,
  },
  User: {
    __resolveReference: (user) => users.find((u) => u.id === user.id),
  },
};

const schema = buildSubgraphSchema({
  typeDefs,
  resolvers,
});

const yoga = createYoga({ schema });
const server = createServer(yoga);

server.listen(4000, () => {
  console.log("🚀 Server ready at http://localhost:4000/graphql");
});
```

Restart the yoga server after making changes. The Grafbase dev server automatically updates the subgraph.

## Products Subgraph

Create a new `products` directory and initialize a new Node.js project:

```bash
mkdir products && cd products
npm init -y
npm install graphql-yoga @apollo/subgraph graphql
```

Create a new file `index.js` and add this code:

```javascript
import { buildSubgraphSchema } from "@apollo/subgraph";
import { parse } from "graphql";
import { createYoga } from "graphql-yoga";
import { createServer } from "http";

const typeDefs = parse(`
  type Query {
    topProducts(first: Int = 5): [Product]
  }

  type Product @key(fields: "id") {
    id: String!
    upc: String!
    name: String!
    price: Int!
  }
`);

const products = [
  {
    id: "1",
    upc: "upc-1",
    name: "Product 1",
    price: 999,
  },
  {
    id: "2",
    upc: "upc-2",
    name: "Product 2",
    price: 1299,
  },
];

const resolvers = {
  Query: {
    topProducts: (_, { first = 5 }) => products.slice(0, first),
  },
  Product: {
    __resolveReference: (reference) => {
      return products.find((p) => p.id === reference.id);
    },
  },
};

const yoga = createYoga({
  schema: buildSubgraphSchema([
    {
      typeDefs,
      resolvers,
    },
  ]),
});

const server = createServer(yoga);

server.listen(4001, () => {
  console.log("🚀 Server ready at http://localhost:4001/graphql");
});
```

The `Product` type has two identifiers, `id` and `upc`, both required to resolve the type. A new query `topProducts` returns the top products. Edit the `grafbase.toml` file to include the new subgraph:

```toml
[subgraphs.accounts]
introspection_url = "http://localhost:4000/graphql"

[subgraphs.products]
introspection_url = "http://localhost:4001/graphql"
```

The Grafbase dev server now has two subgraphs, `accounts` and `products`. Access both by calling the `topProducts` query from the `products` subgraph and the `me` query from the `accounts` subgraph.

## Reviews Subgraph

Create the final `reviews` subgraph. Create a new directory `reviews` and initialize a new Node.js project:

```bash
mkdir reviews && cd reviews
npm init -y
npm install graphql-yoga @apollo/subgraph graphql
```

Create a new file `index.js` and add this code:

```javascript
import { buildSubgraphSchema } from "@apollo/subgraph";
import { parse } from "graphql";
import { createYoga } from "graphql-yoga";
import { createServer } from "http";

// Define the schema
const typeDefs = parse(`
  type Product @key(fields: "id") {
    id: String! @external
    reviews: [Review]
  }

  type User @key(fields: "id") {
    id: ID! @external
    email: String! @external
    username: String! @external
    reviews: [Review]
  }

  type Review {
    body: String!
    author: User!
    product: Product!
  }
`);

// Mock data
const reviews = [
  {
    body: "Great product!",
    authorId: "1",
    productId: "1",
  },
  {
    body: "Would recommend!",
    authorId: "2",
    productId: "2",
  },
];

// Define resolvers
const resolvers = {
  Product: {
    __resolveReference: (reference) => {
      return { id: reference.id };
    },
    reviews: (product) => {
      return reviews.filter((review) => review.productId === product.id);
    },
  },
  User: {
    __resolveReference: (reference) => {
      return { id: reference.id };
    },
    reviews: (user) => {
      return reviews.filter((review) => review.authorId === user.id);
    },
  },
  Review: {
    author: (review) => {
      return { id: review.authorId };
    },
    product: (review) => {
      return { id: review.productId };
    },
  },
};

// Create the yoga server
const yoga = createYoga({
  schema: buildSubgraphSchema([
    {
      typeDefs,
      resolvers,
    },
  ]),
});

// Create and start the server
const server = createServer(yoga);
server.listen(4002, () => {
  console.log("🚀 Server ready at http://localhost:4002/graphql");
});
```

This subgraph extends the `Product` and `User` types from the `products` and `accounts` subgraphs instead of defining queries. Fields with the `@external` directive resolve by the parent subgraph; this subgraph only provides reviews for products and users.

The Grafbase Gateway gets product reviews by sending the product id to find all reviews. The same applies to users.

The review object returns the author and product IDs. The gateway resolves the author and product based on these IDs.

Add the `reviews` subgraph to the `grafbase.toml` file:

```toml
[subgraphs.accounts]
introspection_url = "http://localhost:4000/graphql"

[subgraphs.products]
introspection_url = "http://localhost:4001/graphql"

[subgraphs.reviews]
introspection_url = "http://localhost:4002/graphql"
```

With three subgraphs in the federated graph, query and join data between them:

```graphql
query Users {
  users {
    id
    email
    username
    reviews {
      body
      product {
        id
        name
        price
        upc
      }
    }
  }
}
```

This query returns all users from `accounts`, their reviews from `reviews` and product information from `products`:

```json
{
  "data": {
    "topProducts": [
      {
        "id": "1",
        "name": "Product 1",
        "price": 999,
        "reviews": [
          {
            "author": {
              "id": "1",
              "email": "john@example.com",
              "username": "john_doe"
            },
            "body": "Great product!"
          }
        ]
      },
      {
        "id": "2",
        "name": "Product 2",
        "price": 1299,
        "reviews": [
          {
            "author": {
              "id": "2",
              "email": "bob@example.com",
              "username": "bob_dole"
            },
            "body": "Would recommend!"
          }
        ]
      }
    ]
  }
}
```

Click "Response Query Plan view" in Pathfinder to see the query plan:

![Query Plan](/images/docs/quickstart/query-plan.png)

The query plan shows how the federated graph resolves queries. It first gets `topProducts` from `products`, then gets `_entities` from `reviews` with product IDs from `topProducts`, and finally gets `_entities` from `accounts` with user IDs from `reviews`. The Grafbase Gateway minimizes requests and resolves data efficiently. If possible, it runs some queries in parallel to speed up response time.

## Using the @requires Directive

Our actual reviews graph does not hold the user ID. The `@requires` directive lets the reviews graph define what fields it requires when querying user reviews. The graph uses a secondary key with username and email to fetch reviews . Add the `@requires` directive to the `reviews` field in the `User` type. A different subgraph resolves the email and username fields marked with the `@external` directive.

```graphql
type User @key(fields: "id") {
  id: ID! @external
  email: String! @external
  username: String! @external
  reviews: [Review] @requires(fields: "email username")
}
```

We can now modify our reviews subgraph to use the `email` and `username` fields to fetch the reviews based on these fields:

```javascript
const resolvers = {
  User: {
    __resolveReference: (reference) => {
      return {
        // The gateway will call this edge first, providing us the email and username fields which we add to the response.
        email: reference.email,
        username: reference.username,
      };
    },
    reviews: (user) => {
      // We can now use the email and username fields to fetch the reviews.
      return reviews.filter(
        (review) =>
          review.email === user.email && review.username === user.username,
      );
    },
  },
};
```

We also need to modify the `User` type in the accounts subgraph to include the `email` and `username` fields as a secondary key:

```graphql
type User @key(fields: "id") @key(fields: "email username") {
  id: ID!
  email: String!
  username: String!
}
```

And finally modify the resolver for a `User` to allow querying by email and username:

```javascript
const resolvers = {
  User: {
    __resolveReference: (user) => {
      if (user.id) {
        return users.find((u) => u.id === user.id);
      } else {
        return users.find(
          (u) => u.email === user.email && u.username === user.username,
        );
      }
    },
  },
};
```

Restart the subgraph and run a query to see the results:

```graphql
query {
  topProducts {
    name
    price
    reviews {
      body
      author {
        id
        username
      }
    }
  }
}
```

Even if our reviews graph does not hold the user ID, the gateway can resolve the reviews based on the email and username fields. The ID of the author is fetched from the accounts subgraph.

## Publish the Federated Graph

After creating and testing the subgraphs, publish the graph to Grafbase Platform. Create a new graph in the [Grafbase Dashboard](/dashboard).

![Create New Graph](/images/docs/quickstart/create-graph.png)

Name the graph `quickstart` and click "Create Graph". Use the graph reference to publish the graph.

**Note**: for the following steps, we assume you have [installed the Grafbase CLI](/docs/cli/installation#installation) and either [logged in](/docs/cli/commands/login) or set the `GRAFBASE_ACCESS_TOKEN` environment variable to a valid access token. Access tokens can be created from the dashboard.

From the terminal, publish the subgraphs. First introspect the running `accounts` subgraph, then pipe output to publish. Provide the subgraph name, URL, commit message and `organization-name/graph` slug:

```bash
grafbase introspect http://localhost:4000/graphql \
    | grafbase publish \
        --name accounts \
        --url http://localhost:4000/graphql \
        --message "init accounts" \
        my-org/quickstart
```

Repeat for `products` and `reviews`:

```bash
grafbase introspect http://localhost:4001/graphql \
    | grafbase publish \
        --name products \
        --url http://localhost:4001/graphql \
        --message "init products" \
        my-org/quickstart

grafbase introspect http://localhost:4002/graphql \
    | grafbase publish \
        --name reviews \
        --url http://localhost:4002/graphql \
        --message "init reviews" \
        my-org/quickstart
```

The schema and subgraphs appear in the [Grafbase Dashboard](/dashboard) after publishing.

## Grafbase Gateway

The [Grafbase Gateway](/docs/gateway/installation) deploys as a single binary in your infrastructure. The gateway optimizes for production while sharing code with dev. It automatically detects and updates on federated graph changes.

After installation, create an access token in organization settings:

![New Access Token](/images/docs/quickstart/access-tokens.png)

Export it and start the gateway:

```bash
export GRAFBASE_ACCESS_TOKEN="ey..."
grafbase-gateway --graph-ref quickstart
```

Use Pathfinder in the Grafbase Dashboard to query the federated graph. Set the endpoint URL to http://127.0.0.1:5000/graphql before the first query.

Deploy a production gateway to a server with proper domain and SSL. For testing, configure the local gateway to trace all requests. Edit `grafbase.toml`:

```toml
[telemetry.tracing]
sampling = 1
```

Restart the gateway:

```bash
grafbase-gateway --graph-ref quickstart --config grafbase.toml
```

Return to Pathfinder, run the previous query:

```graphql
query Users {
  users {
    id
    email
    username
    reviews {
      body
      product {
        id
        name
        price
        upc
      }
    }
  }
}
```

Click "Response Trace view" to see sequential queries to `accounts`, `reviews`, and `products`:

![Trace](/images/docs/quickstart/tracing.png)

## Schema Checks

It is a good practice to run schema checks before deploying changes to the federated graph.

Enable operation checks for the production branch in schema checks settings for best results:

![Operation checks](/images/docs/quickstart/schema-checks.png)

Try changing a queried field. Make the username optional in `accounts`:

```graphql
type Query {
  users: [User!]!
}

type User @key(fields: "id") {
  id: ID!
  email: String!
  username: String
}
```

Restart the `accounts` subgraph and run schema checks against the federated graph:

```bash
grafbase introspect http://localhost:4000/graphql \
    | grafbase check --name accounts my-org/quickstart
```

The check returns an error because clients queried `username` in the past seven days:

```
❌ [Error] The field `User.username` became optional, but clients do not expect null.
```

You can fix the error by making sure no clients query `username` for the configured period, or by making the field non-optional.

## Client Analytics

Define these headers in clients using the Grafbase Gateway federated graph:

- `x-grafbase-client-name` for client name
- `x-grafbase-client-version` for client version

These headers let Grafbase analytics show which clients access which fields, helping track field usage as schemas grow.

## Conclusion

This guide showed how to create and federate three subgraphs, use Grafbase Gateway to query them, and publish to Grafbase Enterprise Platform.

Grafbase Gateway leads the market in GraphQL gateway speed and aims for full GraphQL Federation v2 compatibility. We continuously improve and add features. [Contact us](/contact) with questions or feedback.

Learn how to build, federate, and publish GraphQL subgraphs with Grafbase Gateway.

Introduction to GraphQL Federation, a powerful tool for building scalable and distributed GraphQL APIs.

Introduction to GraphQL Federation

In this guide, we will walk you through how to install the Grafbase Enterprise Platform to a Kubernetes cluster. For simplicity, in this guide we use [kind](https://kind.sigs.k8s.io/) to create a local Kubernetes cluster.

## Prerequisites

Before you start the installation, make sure you have the following prerequisites:

- [Kubernetes IN Docker](https://kind.sigs.k8s.io/)
- [Helm](https://helm.sh/)

## Creating the Kind Cluster

First, create a kind cluster. Use the following configuration for the cluster:

```yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      # api
      - containerPort: 30080
        hostPort: 30080
        protocol: TCP
      # dashboard
      - containerPort: 30081
        hostPort: 30081
        protocol: TCP
      # postgres
      - containerPort: 30432
        hostPort: 30082
        protocol: TCP
      # clickhouse
      - containerPort: 30900
        hostPort: 30083
        protocol: TCP
      # minio api
      - containerPort: 30801
        hostPort: 30084
        protocol: TCP
      # minio console
      - containerPort: 30800
        hostPort: 30085
        protocol: TCP
      # gateway
      - containerPort: 30500
        hostPort: 30086
        protocol: TCP
      # telemetry sink
      - containerPort: 30431
        hostPort: 30087
        protocol: TCP
```

Save the configuration to a file, for example `kind-config.yaml`, and create the cluster:

```bash
kind create cluster --name grafbase-enterprise-platform --config kind-config.yaml
kubectl config use-context kind-grafbase-enterprise-platform
```

## Installing the Grafbase Enterprise Platform

Before you start the installation, log in to the grafbase enterprise repository:

```bash
helm registry login helm.grafbase.com --username me@company.com --password changeme
```

When done, download the Grafbase Enterprise Platform Helm chart:

```bash
helm pull oci://helm.grafbase.com/enterprise-platform/stable/enterprise-platform
```

Create a new file `values.yaml.gotmpl` with the following values:

```yaml
global:
  zitadel:
    enabled: true
  postgresql:
    enabled: true
  clickhouse:
    enabled: false
  minio:
    enabled: true
  kafka:
    enabled: false
  telemetrySink:
    enabled: false
  otelCollector:
    enabled: false
  dashboard:
    enabled: true

api:
  configmap:
    values:
      AWS_ACCESS_KEY_ID: changeme
  service:
    type: NodePort
    nodePort: 30080
  secrets:
    values:
      AWS_SECRET_ACCESS_KEY: changeme

dashboard:
  service:
    type: NodePort
    nodePort: 30081

minio:
  service:
    type: NodePort
    nodePorts:
      api: 30800
  console:
    service:
      type: NodePort
      nodePorts:
        http: 30801
```

Install the Helm chart with the following command:

```bash
helm install grafbase-enterprise-platform enterprise-platform-*.tgz -f values.yaml.gotmpl
```

Wait a bit for the cluster to get ready, and you can see the API web worker crashing due to not being able to access the AWS S3 bucket:

```bash
> kubectl logs grafbase-enterprise-platform-api-web-69644fb98b-djgt2
{"timestamp":"2025-01-20T18:14:10.955429888+00:00","level":"INFO","fields":{"message":"API running at 0.0.0.0:8080"},"target":"api::runtime::std::serve","service":"grafbase-api","branch":"","environment":"local"}
{"timestamp":"2025-01-20T18:14:17.681903592+00:00","level":"ERROR","fields":{"message":"storage error: service error"},"target":"api::runtime::http::handlers","service":"grafbase-api","branch":"","environment":"local"}
```

In this example, use MiniIO as the S3 bucket, and create and set the access key and secret key to the secrets. Start first by opening [MinIO console](http://localhost:30084/login) and log in with user `grafbase` and password `grafbase`. Click on "Access Keys" and create a new access key. Copy the access key and secret key to the values:

```bash
api:
  configmap:
    values:
      AWS_ACCESS_KEY_ID: ACCESS KEY FROM MINIO
  secrets:
    values:
      AWS_SECRET_ACCESS_KEY: SECRET KEY FROM MINIO
```

Upgrade the Helm chart:

```bash
helm upgrade grafbase-enterprise-platform enterprise-platform-*.tgz -f values.yaml.gotmpl
```

After waiting a few seconds, check if the API is running:

```bash
> curl localhost:30080/health
"Healthy"
```

In a real scenario, use a real S3 bucket. Create a bucket `grafbase` in your storage provider, and set the access key and secret key with read and write access to the bucket. You can set the `GRAFBASE_OBJECT_STORAGE_S3_ENDPOINT_URL` configmap value to point to the bucket URL in local setups.

** Note ** The following section assumes you use Zitadel. Zitadel is being deprecated in favor of [integrating directly with your own IdP](/docs/platform/self-hosting/single-sign-on).

The next step involves creating a new Zitadel organization. The official Zitadel chart does not yet support creating a nodePort, so do a trick to be able to access the Zitadel UI from our kind cluster. These steps do not apply to a real cluster, where you have an ingress setup for Zitadel and can access it with a domain name.

Add the following line to your `/etc/hosts` file:

```bash
127.0.0.1 grafbase-enterprise-platform-zitadel
```

Then, add port forwarding to the Zitadel service:

```bash
kubectl port-forward service/grafbase-enterprise-platform-zitadel 30550:8080
```

Open the first-time admin UI by visiting [http://localhost:30081/admin](http://localhost:30081/admin). Click "Run script" followed by "Manage single sign-on".

Log in to Zitadel with the username `zitadel-admin@zitadel.grafbase-enterprise-platform-zitadel` and password `Password1!`. Skip the 2-factor setup for now and enter a new password for the default user.

Next, you will need to set up an identity provider. Any identity provider supported by Zitadel will work. We have specific guides for [GitHub](/guides/installing-grafbase-enterprise-platform#setting-up-single-sign-on-with-github) and [Gitlab](/guides/installing-grafbase-enterprise-platform#setting-up-single-sign-on-with-gitlab).

## Installing the Telemetry Architecture

The Grafbase Enterprise Platform processes telemetry events from the Grafbase Gateway using a service called telemetry sink. To enable this service in your local installation, set the global values to `true` for both the sink and the opentelemetry collector in the `values.yaml.gotmpl` file:

```yaml
global:
  telemetrySink:
    enabled: true
  otelCollector:
    enabled: true
```

Add a node port for the sink to access the sink locally:

```yaml
telemetry-sink:
  service:
    type: NodePort
    nodePort: 30431
  configmap:
    values:
      GRAFBASE_KAFKA_BOOTSTRAP_SERVERS: "list_your_kafka_servers_here"
      GRAFBASE_KAFKA_USERNAME: "change me"
      GRAFBASE_KAFKA_MECHANISM: "SCRAM-SHA-256"
      GRAFBASE_KAFKA_SECURITY_PROTOCOL: "sasl_ssl"
  secrets:
    values:
      SYMMETRIC_ENCRYPTION_SECRET: "must be the same as in the API chart"
      PG_CONNECTION_STRING: "if not set, uses the local postgres"
      GRAFBASE_KAFKA_PASSWORD: "change me"
      CLICKHOUSE_CONNECTION_STRING: "if not set, uses the local clickhouse"
```

For the opentelemetry collector:

```yaml
opentelemetry-collector:
  extraEnvs:
    - name: KAFKA_BROKER
      value: "address of the broker"
    - name: KAFKA_USER
      value: "change me"
    - name: KAFKA_PASSWORD
      value: "change me"
    - name: KAFKA_SASL_MECHANISM
      value: SCRAM-SHA-256
    - name: KAFKA_TLS_INSECURE
      value: "false"
    - name: CLICKHOUSE_ENDPOINT
      value: "must be the same as in the telemetry-sink"
    - name: CLICKHOUSE_DB
      value: "must be the same as in the telemetry-sink"
    - name: CLICKHOUSE_USER
      value: "change me"
    - name: CLICKHOUSE_PASSWORD
      value: "change me"
```

Ensure your Kafka server has a user with the corresponding password having access to the topics: `otlp_metrics`, `otlp_spans`, and `otlp_logs`. After updating these values with Helm, perform a rolling restart of both the opentelemetry collector and the telemetry sink. Finally, verify the logs for both pods to ensure there are no Kafka errors in the output.

## Using Grafbase CLI with the Enterprise Platform

You can define your instance using the [Grafbase CLI](/docs/cli/installation) by setting the URL to your local installation in the CLI login command:

```bash
grafbase login --url http://localhost:30081/
```

Now, you are ready to use the CLI with your local Grafbase Enterprise Platform installation.

## Using the Grafbase Gateway with the Enterprise Platform

To connect the Grafbase Gateway with the Grafbase Enterprise Platform, set the `GRAFBASE_OTEL_URL` environment variable to point to the telemetry sink URL.


## Setting up single-sign on with GitHub

Change the organization to "Grafbase" from the top navigation.

Navigate to "Settings", click "Identity Providers", then "GitHub". To use GitHub as an authentication provider, create a new OAuth application in GitHub. Go to [GitHub OAuth Apps](https://github.com/settings/applications/new), give the app a name and URL, and set the callback URL with the value from Zitadel. Now copy the client ID and the secret created in GitHub to the corresponding fields in Zitadel. Open optional settings, add the scope `user:email`, and check all the checkboxes. Click "Save", scroll up, and click "Activate".

To fetch the user email via GitHub, navigate to "Actions" and click "New". Name the action as "backfillEmail" and fill it with the following snippet:

```javascript
let http = require("zitadel/http")

function backfillEmail(ctx, api) {
  const { human } = ctx.v1.externalUser

  // This is an example of how email is added with GitHub auth
  if (!human.email?.length) {
    const emails = http.fetch('https://api.github.com/user/emails', {
      method: 'GET',
      headers: {
        "Authorization": `Bearer ${ctx.accessToken}`
      }
    }).json()

    const primaryEmailAddress = emails.find(email => email.primary)
    if (primaryEmailAddress) {
      api.setEmail(primaryEmailAddress.email)
    }
  }
}
```

Click "Add", then click the "Add trigger" button. Set the trigger type to "Post Authentication" and actions to "backfillEmail" and "backfillName". Click "Save".

Now navigate to the [Grafbase Dashboard](http://localhost:30081) and log in with your GitHub credentials. The dashboard should prompt you to create a new organization.


## Setting up single-sign on with GitLab

This guide applies to both self-hosted instances of GitLab and gitlab.com.

Once logged in to the Zitadel dashboard, change the organization to "Grafbase" from the top navigation. Navigate to "Settings", click "Identity Providers", then "Gitlab".

![Selecting the Grafbase organization](/images/docs/ep/gitlab-sso/select_grafbase_organization.png)

![Selecting the Gitlab provider](/images/docs/ep/gitlab-sso/select_gitlab_sso.png)

You will see a callback link, which you can already copy. Keep this tab open. Then navigate to Gitlab, and in group settings, select "Applications" and create a new application. Insert the callback link you copied from Zitadel, and create the app with the following scopes: `openid`, `profile`, `email`.

![Gitlab UI to create the application](/images/docs/ep/gitlab-sso/gitlab_group_applications.png)

![Copy the application id and secret from the Gitlab application creation screen](/images/docs/ep/gitlab-sso/gitlab_copy_access_key.png)

Gitlab will give you an application ID and secret. Copy these values, and go back to the Zitadel page where you copied the callback URL. Tick the "Automatic creation" and "Automatic update" boxes, and create the provider.

![Form to create the identity provider in Zitadel](/images/docs/ep/gitlab-sso/gitlab_provider_create.png)

You should now be able to sign in with Gitlab in the Grafbase dashboard. On first sign in, you will be prompted to create a new organization. Subsequent users will be able to log in with Gitlab, but there is a last step to complete before they are also automatically added to your organization.

Go back to the Zitadel dashboard. Navigate to the Grafbase organization, then to "Settings", then "Verified domains". Add the domain name used by the user emails associated to the Gitlab accounts you will use to log in.

In the postgres database used by your Enterprise Platform deployment, there should be a single row in the `accounts` table. Update the value for the `saml_domain` column to match the domain you just configured in Zitadel.

Now anytime someone logs in to the dashboard, and their email address matches the configured domain, they will automatically be added to your organization.

Also see the [Zitadel guide on using Gitlab as an IdP](https://zitadel.com/docs/guides/integrate/identity-providers/gitlab).

Learn how to install the Grafbase Enterprise Platform to a Kubernetes cluster

Installing the Grafbase Enterprise Platform

Grafbase and Apollo GraphOS both implement the GraphQL Federation v2 spec. This means you can run a federated graph composed from the same subgraphs using either the Grafbase Gateway or Apollo Router. This guide will assist you in migrating from Apollo to Grafbase.

The major components are comparable:

| Component       | Apollo        | Grafbase          |
| --------------- | ------------- | ----------------- |
| Gateway         | Apollo Router | Grafbase Gateway  |
| Schema Registry | GraphOS       | Grafbase Platform |
| CLI             | Rover         | Grafbase CLI      |

Additionally, the Grafbase Platform can be fully self-hosted in your own infrastructure for maximum security and control. [Contact sales](/contact/sales) if you want to learn more about the Grafbase Enterprise Platform.

We will explore two scenarios: first, how to run the Grafbase Gateway without migrating any of your GraphOS setup, and second, how to migrate over your federated graph from GraphOS to Grafbase.

## Trying Grafbase Gateway only

If you want to try Grafbase Gateway without migrating your GraphOS setup, you can do so by starting Grafbase Gateway with your existing Federated Graph.

First, you need to [install Grafbase Gateway](/docs/gateway/installation):

```bash
curl -fsSL https://grafbase.com/downloads/gateway | bash
```

Next, you will need the schema of your federated graph. You can download it from the GraphOS Studio UI or via the `rover` CLI:

```bash
rover supergraph fetch my-graph@my-variant > federated.graphql
```

Now you can start the Grafbase Gateway with your Federated Graph:

```bash
grafbase-gateway --schema federated.graphql
```

You are now up and running! You can send queries to the Grafbase Gateway and see it work with your Federated Graph. To explore all the features and configuration options of the gateway, check out the [relevant documentation](/docs/gateway/installation).

When you are ready for a full migration, you can proceed to the next section. We're also happy to provide assistance, just [contact us](/contact)!

## Migrating a Federated Graph from Apollo GraphOS to Grafbase

This part of the guide will walk you through setting up your Federated Graph on Grafbase, assuming you already have running subgraphs that have been published to GraphOS.

### Step 1: Exporting your subgraph schemas

First, you will need the [Grafbase CLI](https://grafbase.com/cli). You can either use `npx grafbase` or install it with the following command:

```bash
curl -fsSL https://grafbase.com/downloads/cli | bash
```

You can list all your subgraphs as shown in the following example:

```bash
rover subgraph list Spotify-Demo-Graph-4m8tpk@current --format=plain
Listing subgraphs for Spotify-Demo-Graph-4m8tpk@current using credentials from the default profile.
┌──────────┬──────────────────────────────────────────────┬────────────────────────────┐
│   Name   │                 Routing Url                  │        Last Updated        │
├──────────┼──────────────────────────────────────────────┼────────────────────────────┤
│ spotify  │ https://showcase-spotify.apollographql.com/  │ 2024-05-06 15:21:54 +02:00 │
├──────────┼──────────────────────────────────────────────┼────────────────────────────┤
│ playback │ https://showcase-playback.apollographql.com/ │ 2024-05-06 15:21:54 +02:00 │
└──────────┴──────────────────────────────────────────────┴────────────────────────────┘
```

You can pick the subgraphs you want to migrate and publish them manually, or automate the process with a small script.

To publish manually, you can use `rover subgraph fetch` to download the schema of a subgraph, then `grafbase publish` to publish it:

```bash
rover subgraph fetch Spotify-Demo-Graph-4m8tpk@current > spotify.graphql
npx grafbase publish --schema spotify.graphql --url=https://showcase-spotify.apollographql.com/ --name=spotify
```

To automate the process, you can use a script like the following:

```bash
GRAPHOS_GRAPH_REF=Spotify-Demo-Graph-4m8tpk@current
GRAFBASE_GRAPH_REF=my-account/my-graph@main

rover subgraph list $GRAPHOS_GRAPH_REF --format=json | jq -c '.data.subgraphs[] | {name: .name, url: .url}' > subgraphs.json

while IFS= read -r line; do
  name=$(echo "$line" | jq -r '.name')
  url=$(echo "$line" | jq -r '.url')
  rover subgraph fetch $GRAPHOS_GRAPH_REF --name "$name" > "$name.graphql"
  grafbase publish $GRAFBASE_GRAPH_REF --name "$name" --url "$url" --schema "$name.graphql"
done < subgraphs.json
```

This takes care of the initial setup.

### Step 2: Setting up subgraph publishing

You should also make sure that you also publish to Grafbase in your release process wherever you already publish to GraphOS with `rover subgraph publish`. Read more on `grafbase publish` on [the dedicated docs page](/docs/platform/schema-registry#publishing-a-subgraph). This will ensure your subgraphs are up to date on both platforms for the duration of your migration.

### Step 3: Setting up schema checks

Similarly, you should set up schema checks on Grafbase. You can use the `grafbase check` command to check your schema against the Grafbase Platform. Read more on `grafbase check` on [the dedicated docs page](/docs/platform/schema-registry).

### Step 4: Setting up Grafbase Gateway

Whether you use the binary directly, the [official Docker image](https://github.com/grafbase/grafbase/pkgs/container/gateway), or your own preferred deployment method, you can start the Grafbase Gateway with the Federated Graph SDL directly, as in the previous section, or use the graph reference for your gateway to automatically pick up the latest Federated Graph schema whenever it gets published:

```bash
GRAFBASE_ACCESS_TOKEN=token ./grafbase-gateway \
  --config grafbase.toml \
  --graph-ref graph@branch
```

The `--config` argument is optional, but to start the gateway with a graph ref, the access token is mandatory. You can get an access token from the Grafbase dashboard.

For more information on the features, configuration options, and ways to run the gateway, see the dedicated [docs section](/docs/gateway/installation).

You now have the schema registry populated and the gateway set up. You are running your Federated Graph on Grafbase!

## Common workflows

### Publishing a subgraph

Rover:

```bash
rover subgraph publish my-graph@my-variant --name my-subgraph --schema ./my-subgraph.graphql --routing-url https://my-subgraph.example.comjk
```

Grafbase:

```bash
npx grafbase publish my-graph@branch-name --name my-subgraph --schema ./my-subgraph.graphql --url https://my-subgraph.example.com
```

### Running schema checks

Rover:

```bash
rover subgraph check my-graph@my-variant --name my-subgraph --schema ./my-subgraph.graphql
```

Grafbase:

```bash
npx grafbase check my-graph@branch-name --name my-subgraph --schema ./my-subgraph.graphql
```

Migrate your federated graph to Grafbase in minutes.

Learn how to migrate your federated graph from Apollo to Grafbase.

Migrating from Apollo

Grafbase Gateway extensions give you powerful ways to extend your gateway's functionality. You can add custom logic like authentication, authorization, and data transformation.

This guide shows you how to implement a custom resolver extension for your Grafbase gateway. You'll create two new directives: `@restEndpoint` and `@rest`, which let you define REST endpoints and map them to GraphQL queries.

![Building your own Extension](/images/blog/introducing-grafbase-extensions-build.png)

## Prerequisites

Before you begin, you need:

- A working [Rust installation with rustup](https://rustup.rs/)
- The latest version of the [Grafbase CLI](/docs/cli/installation)
- The latest version of the [Grafbase Gateway](/docs/gateway/installation)

## Creating a Rest Extension

The `grafbase` command-line tool helps you create a new extension. Run this command:

```bash
grafbase extension init --type resolver rest
```

This creates a new `rest` directory with these files and directories:

```text
rest
├── Cargo.toml
├── definitions.graphql
├── extension.toml
├── src
│   └── lib.rs
└── tests
    └── integration_tests.rs
```

- `Cargo.toml` configures the Rust project. Add dependencies and build configuration here.
- `definitions.graphql` contains GraphQL directives and types for your extension.
- `extension.toml` configures the extension with its name, version, kind, and other options.
- `src/lib.rs` contains your extension's main implementation code.
- `tests/integration_tests.rs` contains integration tests for your extension.

For this demo we have to modify the grafbase-sdk dependency, and add the `jq-selection` feature flag to the `Cargo.toml` file:

```bash
cargo add grafbase-sdk --features jq-selection
```

## Extension Directives

The `rest` extension uses two directives to define the REST API endpoint and the HTTP method to use:

```graphql
extend schema @link(url: "https://specs.grafbase.com/grafbase", import: ["InputValueSet", "UrlTemplate"])

directive @restEndpoint(
  name: String,
  baseUrl: String!
) repeatable on SCHEMA

directive @rest(
  endpoint: String,
  method: HttpMethod
  path: UrlTemplate!
  selection: UrlTemplate
) on FIELD_DEFINITION

enum HttpMethod {
  GET
  POST
  PUT
  DELETE
}
```

- `@restEndpoint` defines the REST API endpoint. You can write this directive multiple times on the schema definition.
- `@rest` defines the REST API path and selects the endpoint to use. Add this directive to any field definition that should trigger the extension.

Save the directives and input types to a file called `definitions.graphql`.

An example of a subgraph schema using the directives:

```graphql
@restEndpoint(
  name: "restCountries",
  baseURL: "https://restcountries.com/v3.1"
)

type Country {
  name: String!
}

type Query {
  listAllCountries: [Country!]! @rest(
    endpoint: "restCountries",
    method: GET,
    path: "/all"
    selection: "[.[] | { name: .name.official }]"
  )
}
```

We created one REST endpoint called `restCountries`. In the `listAllCountries` field definition, we added the `@rest` directive to define the REST API path and endpoint to use, along with the HTTP method GET.

The `selection` argument defines the GraphQL selection set that transforms the REST API response into a GraphQL response. This follows the [jq query syntax](https://jqlang.org/manual/), which we implement in the extension.

## Extension Configuration

Add the following configuration to `extension.toml`:

```toml
[extension]
name = "rest"
version = "0.1.0"
kind = "resolver"

[directives]
definitions = "definitions.graphql"
field_resolvers = ["rest"]
```

- `name` identifies the extension.
- `version` specifies the extension version.
- `kind` sets the extension type to either `resolver` or `auth`.
- `definitions` points to the GraphQL schema file we created.
- `field_resolvers` lists the field resolver names that the extension provides and triggers.

## Implementation

Find up to date information on the Grafbase Rust SDK in the [official documentation](https://docs.rs/grafbase-sdk/latest/grafbase_sdk/#resolver-example).

First install all the needed dependencies:

```bash
cargo add serde serde_json http
cargo add url --features serde_json
```

Open the `src/lib.rs` source code in an editor of your choice. We recommend using an editor with Rust IDE features, such as [RustRover](https://www.jetbrains.com/rust/) or any other editor with language server protocol support, combined with the [rust-analyzer](https://rust-analyzer.github.io/).

First create a struct that acts as a gateway resolver extension:

```rust
use grafbase_sdk::jq_selection::JqSelection;

#[derive(ResolverExtension)]
struct RestExtension {
    endpoints: Vec<RestEndpoint>,
    jq: JqSelection,
}
```

Our extension tracks all `@restEndpoint` directives in the `endpoints` field, and all compiled selection filters in the `filters` field. The `arena` is an arena allocator needed later for allocating memory for the selection parser.

Implement the `Extension` trait for the `RestExtension`:

```rust
impl Extension for RestExtension {
    fn new(schema_directives: Vec<Directive>, _: Configuration) -> Result<Self, Box<dyn std::error::Error>> {
        let mut endpoints = Vec::<RestEndpoint>::new();

        // Iterates over all `@restEndpoint` directives from the subgraph.
        for directive in schema_directives {
            // Creates a new `RestEndpoint` from the given `Directive`.
            let endpoint = RestEndpoint {
                subgraph_name: directive.subgraph_name().to_string(),
                args: directive.arguments()?,
            };

            endpoints.push(endpoint);
        }

        // Sorts the endpoints by name and subgraph name. This allows fast lookup
        // and good cache efficiency.
        endpoints.sort_by(|a, b| {
            let by_name = a.args.name.cmp(&b.args.name);
            let by_subgraph = a.subgraph_name.cmp(&b.subgraph_name);
            by_name.then(by_subgraph)
        });

        Ok(Self {
            endpoints,
            jq: JqSelection::default(),
        })
    }
}
```

The `RestEndpoint` struct uses [Serde](https://docs.rs/serde/latest/serde/) to deserialize the `@restEndpoint` directive:

```rust
#[derive(Debug)]
pub struct RestEndpoint {
    pub subgraph_name: String,
    pub args: RestEndpointArgs,
}

#[derive(serde::Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
pub struct RestEndpointArgs {
    pub name: String,
    #[serde(rename = "baseURL")]
    pub base_url: Url,
}
```

When we call the `arguments()` method from the `Directive` in the constructor, it deserializes the arguments into the `RestEndpointArgs` and `HttpSettings` structs.

Next implement the `Resolver` trait for the `RestExtension` struct:

```rust
impl Resolver for RestExtension {
    fn resolve_field(
        &mut self,
        _: SharedContext,
        directive: Directive,
        _: FieldDefinition,
        _field_inputs: FieldInputs<'_>,
    ) -> Result<FieldOutput, Error> {
        ...
    }

    fn resolve_subscription(
        &mut self,
        _: SharedContext,
        _: Directive,
        _: FieldDefinition,
    ) -> Result<Box<dyn Subscription>, Error> {
        unreachable!()
    }
}
```

We only need the `directive` argument, which contains the arguments provided in the `@rest` directive. We access the arguments using the `arguments()` method on the `Directive` struct:

```rust
let rest: Rest<'_> = directive.arguments().map_err(|e| Error {
    extensions: Vec::new(),
    message: format!("Could not parse directive arguments: {e}"),
})?;
```

This deserializes the arguments into the `Rest` struct, defined as:

```rust
#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Rest<'a> {
    pub endpoint: &'a str,
    pub method: HttpMethod,
    pub path: &'a str,
    pub selection: &'a str,
}

#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "UPPERCASE")]
pub enum HttpMethod {
    Get,
    Post,
    Put,
    Delete,
}
```

Next find an endpoint in the `@restEndpoint` directives. Every subgraph must define its own endpoints, but the extension sees all subgraphs and their endpoints. That's why we need to do the lookup with endpoint and subgraph names:

```rust
let Some(endpoint) = self.get_endpoint(rest.endpoint, directive.subgraph_name()) else {
    return Err(Error {
        extensions: Vec::new(),
        message: format!("Endpoint not found: {}", rest.endpoint),
    });
};
```

The easiest lookup method would use a `HashMap`, but for small amounts of endpoints a sorted vector can fit in the CPU cache, and provides faster lookup speed:

```rust
impl RestExtension {
    pub fn get_endpoint(&self, name: &str, subgraph_name: &str) -> Option<&RestEndpoint> {
        self.endpoints
            .binary_search_by(|e| {
                let by_name = e.args.name.as_str().cmp(name);
                let by_subgraph = e.subgraph_name.as_str().cmp(subgraph_name);

                by_name.then(by_subgraph)
            })
            .map(|i| &self.endpoints[i])
            .ok()
    }
}
```

Next combine the base URL with the endpoint path:

```rust
let mut url = endpoint.args.http.base_url.clone();
let path = rest.path.strip_prefix("/").unwrap_or(rest.http.path);

if !path.is_empty() {
    let mut path_segments = url.path_segments_mut().map_err(|_| Error {
        extensions: Vec::new(),
        message: "Could not parse URL".to_string(),
    })?;

    path_segments.push(path);
}
```

Now call the REST endpoint and parse the response:

```rust
// Build a new HTTP request, using the method from our deserialized `@rest` directive.
let request = HttpRequest::builder(url, rest.method.into()).build();

// Execute the HTTP request and handle any errors.
let result = http::execute(&request).map_err(|e| Error {
    extensions: Vec::new(),
    message: format!("HTTP request failed: {e}"),
})?;

// Check if the HTTP request succeeded.
if !result.status().is_success() {
    return Err(Error {
        extensions: Vec::new(),
        message: format!("HTTP request failed with status: {}", result.status()),
    });
}

// Parse the response body as arbitrary JSON.
let data: serde_json::Value = result.json().map_err(|e| Error {
    extensions: Vec::new(),
    message: format!("Error deserializing response: {e}"),
})?;
```

For the http method conversion, implement a `From` trait from our type to `http::Method`:

```rust
#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "UPPERCASE")]
pub enum HttpMethod {
    Get,
    Post,
    Put,
    Delete,
}

impl From<HttpMethod> for ::http::Method {
    fn from(method: HttpMethod) -> Self {
        match method {
            HttpMethod::Get => Self::GET,
            HttpMethod::Post => Self::POST,
            HttpMethod::Put => Self::PUT,
            HttpMethod::Delete => Self::DELETE,
        }
    }
}
```

Now continue our `resolve_field` implementation by using the filter we just created, and add the final JSON to the response:

```rust
let filtered = self
    .jq_selection
    .select(rest.selection, data)
    .map_err(|e| format!("Error selecting result value: {e}"))?
    .collect::<Result<Vec<_>, _>>();

Ok(match filtered {
    Ok(filtered) => {
        // Is a list or a single item expected here?
        if filtered.len() == 1 {
            FieldOutput::new(field_inputs, filtered.into_iter().next().unwrap())?
        } else {
            FieldOutput::new(field_inputs, filtered)?
        }
    }
    Err(error) => FieldOutput::error(field_inputs, format!("Failed to filter with selection: {}", error)),
})
```

Find the full example in the [grafbase repository](https://github.com/grafbase/grafbase/tree/main/extensions/rest/src).

## Testing

The Grafbase SDK includes test utilities for testing your extensions. `grafbase extension init` includes the required dependencies, but we need to add one more crate to start testing:

```bash
cargo add --dev wiremock
```

Find the tests in the `tests/integration_tests.rs` file. See the full example in the [grafbase repository](https://github.com/grafbase/grafbase/tree/main/extensions/rest/tests).

Let's write a test that:

- Starts a mock REST server in a separate thread
- Creates a virtual subgraph and configures the REST extension
- Creates a test runner that composes the subgraph and starts the Grafbase Gateway
- Runs a GraphQL query against the gateway and asserts the response

Here's the function that generates a virtual subgraph:

```rust
fn subgraph(rest_endpoint: &str) -> ExtensionOnlySubgraph {
    let extension_path = std::env::current_dir().unwrap().join("build");
    let path_str = format!("file://{}", extension_path.display());

    let schema = formatdoc! {r#"
        extend schema
          @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
          @link(url: "{path_str}", import: ["@restEndpoint", "@rest"])

        @restEndpoint(
          name: "endpoint",
          baseURL: "{rest_endpoint}"
        )

        type Query {{
          users: [User!]! @rest(
            endpoint: "endpoint",
            method: GET,
            path: "/users"
            selection: "[.[] | {{ id, name, age }}]"
          )
        }}

        type User {{
          id: ID!
          name: String!
          age: Int!
        }}
    "#};

    DynamicSchema::builder(schema)
        .into_extension_only_subgraph("test", &extension_path)
        .unwrap()
}
```

The schema takes the extension build directory and mock REST service URL as parameters.

With this function ready, we can write our first test:

```rust
#[tokio::test]
async fn get_all_fields() {
    // Our mock response from the REST service
    let response_body = json!([
        {
            "id": "1",
            "name": "John Doe",
            "age": 30,
        },
        {
            "id": "2",
            "name": "Jane Doe",
            "age": 25,
        }
    ]);

    let template = ResponseTemplate::new(200).set_body_json(response_body);
    let mock_server = mock_server("/users", template).await;

    // Generate the virtual subgraph with the URL our mock server is running on
    let subgraph = subgraph(&mock_server.uri());

    // Build a test config with the subgraph and enable networking. This tries to look for
    // the grafbase-gateway and grafbase binaries from the PATH. You can also point it to the specific
    // binaries by calling the `with_gateway` and `with_cli` methods.
    let config = TestConfig::builder()
        .with_subgraph(subgraph)
        .enable_networking()
        .build("")
        .unwrap();

    // Start the Grafbase Gateway and return a runner instance to run queries against.
    let runner = TestRunner::new(config).await.unwrap();

    let query = indoc! {r#"
        query {
          users {
            id
            name
            age
          }
        }
    "#};

    let result: serde_json::Value = runner.graphql_query(query).send().await.unwrap();

    insta::assert_json_snapshot!(result, @r#"
    {
      "data": {
        "users": [
          {
            "id": "1",
            "name": "John Doe",
            "age": 30
          },
          {
            "id": "2",
            "name": "Jane Doe",
            "age": 25
          }
        ]
      }
    }
    "#);
}
```

Run the tests with `cargo`:

```bash
cargo test
```

Make gateway errors visible by calling `enable_stdout` and `enable_stderr` methods on the `TestConfig` builder.

## Installation

Build the extension after completing development:

```bash
grafbase extension build
```

Copy the `build` directory to your Grafbase project:

```bash
cp -r build/* path/to/your/grafbase/project/rest/
```

Add the extension to the gateway configuration:

```toml
[extensions]
rest = { path = "rest" }
```

Launch the gateway:

```bash
grafbase-gateway --schema federated-schema.graphql --config grafbase.toml
```

Build custom gateway resolver extensions with Grafbase.

Learn how to implement a custom resolver extension for your Grafbase gateway.

Guides