Tutorials

Tutorial 1: Federate a REST API

Goal: Expose an existing REST API through your GraphQL gateway.

Step 1 — Define the GraphQL schema with @rest directives

# users-api.graphql
directive @rest(
  path: String!
  method: String = "GET"
  owner: String!
  ttl: Int
) on FIELD_DEFINITION

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

type Query {
  user(id: ID!): User
    @rest(path: "/users/{args.id}", owner: "users-api")
  users: [User!]!
    @rest(path: "/users", owner: "users-api")
}

type Mutation {
  createUser(name: String!, email: String!): User
    @rest(path: "/users", method: "POST", owner: "users-api")
}

Step 2 — Push to router

hyperroute push --local \
  --name users-api \
  --schema users-api.graphql \
  --url http://localhost:4001 \
  --subgraph-type rest

Step 3 — Query through the gateway

# REST GET /users/1 is called automatically
curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ user(id: \"1\") { name email } }"}'

The router reads the @rest directive, builds an HTTP GET request to /users/1, and returns the result as GraphQL.

---

Tutorial 2: Federate a gRPC Service

Goal: Expose a gRPC service through your GraphQL gateway.

Step 1 — Define the GraphQL schema with @grpc directives

# inventory.graphql
directive @grpc(
  service: String!
  method: String!
  owner: String!
  ttl: Int
) on FIELD_DEFINITION

type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Float!
  stock: Int!
}

type Query {
  product(id: ID!): Product
    @grpc(
      service: "inventory.v1.ProductService"
      method: "GetProduct"
      owner: "inventory"
    )
}

Tip: The service must match the fully qualified service name in your .proto file (i.e., package.ServiceName).

Step 2 — Push to router

hyperroute push --local \
  --name inventory \
  --schema inventory.graphql \
  --url grpc://localhost:50051 \
  --subgraph-type grpc \
  --grpc-service inventory.v1.ProductService

Step 3 — Query through the gateway

# gRPC GetProduct is called automatically
curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ product(id: \"prod-1\") { name price stock } }"}'

---

Tutorial 3: Mixed Federation (GraphQL + REST + gRPC)

Push all three types into a unified supergraph:

# 1. GraphQL service
hyperroute push --local \
  --name accounts \
  --schema accounts.graphql \
  --url http://localhost:3006/graphql

# 2. REST service
hyperroute push --local \
  --name users \
  --schema users.graphql \
  --url http://localhost:4001 \
  --subgraph-type rest

# 3. gRPC service
hyperroute push --local \
  --name inventory \
  --schema inventory.graphql \
  --url grpc://localhost:50051 \
  --subgraph-type grpc \
  --grpc-service inventory.v1.ProductService

Query across all backends

# This single query spans GraphQL, REST, and gRPC
curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ user(id: \"1\") { name } product(id: \"prod-1\") { name price } }"}'

The router resolves user via REST (GET /users/1) and product via gRPC (GetProduct) in parallel, returning a unified GraphQL response.