Overview - WunderGraph

Cosmo ConnectRPC

Cosmo ConnectRPC gives you the best of both worlds: the schema design and composition power of GraphQL with the universal reach of REST and type-safe SDKs. Define your API once as GraphQL operations, and let consumers interact through generated clients, standard HTTP endpoints, or high-performance gRPC — no GraphQL expertise required on the consumer side.

From GraphQL Operations to Multiple Interfaces

GraphQL Operation Collections
OpenAPI Specification
TypeScript SDK
Go SDK

The following example shows how a single GetEmployeeById GraphQL operation becomes consumable through multiple interfaces:

The source GraphQL operation that defines the API contract:

query GetEmployeeById($id: Int!) {
  employee(id: $id) {
    id
    details {
      forename
      surname
    }
  }
}

Automatically generated OpenAPI specification:

/employees.v1.HrService/GetEmployeeById:
  post:
    tags:
      - employees.v1.HrService
    summary: GetEmployeeById
    operationId: employees.v1.HrService.GetEmployeeById
    parameters:
      - name: Connect-Protocol-Version
        in: header
        required: true
        schema:
          $ref: '#/components/schemas/connect-protocol-version'
      - name: Connect-Timeout-Ms
        in: header
        schema:
          $ref: '#/components/schemas/connect-timeout-header'
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/employees.v1.GetEmployeeByIdRequest'
      required: true
    responses:
      default:
        description: Error
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/connect.error'
      "200":
        description: Success
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/employees.v1.GetEmployeeByIdResponse'

Type-safe TypeScript client code:

import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { HrService } from "@my-org/sdk/employees/v1/service_connect";

const transport = createConnectTransport({
  baseUrl: "http://localhost:5026",
});

const client = createClient(HrService, transport);

// Request and response are fully typed
const response = await client.getEmployeeById({ id: 1 });
console.log(`Employee: ${response.employee?.details?.forename}`);

Type-safe Go client code:

import (
    "context"
    "connectrpc.com/connect"
    employeesv1 "github.com/my-org/sdk/gen/go/employees/v1"
    "github.com/my-org/sdk/gen/go/employees/v1/employeesv1connect"
)

client := employeesv1connect.NewHrServiceClient(
    http.DefaultClient,
    "http://localhost:5026",
)

req := connect.NewRequest(&employeesv1.GetEmployeeByIdRequest{
    Id: 1,
})

res, err := client.GetEmployeeById(context.Background(), req)
// Response is strongly typed
fmt.Printf("Employee: %s\n", res.Msg.Employee.Details.Forename)

Why This Matters

While GraphQL is an excellent interface for schema design and composition, it is not universally consumable. Many API consumers - due to existing tooling, security policies, performance requirements, or language ecosystems - rely on REST, RPC, or generated SDKs rather than constructing GraphQL queries directly. Without a unified approach, platform teams often end up maintaining parallel APIs and duplicated contracts, leading to drift, inconsistent behavior, and higher operational overhead.

Architectural Benefits

ConnectRPC addresses fundamental infrastructure and operational challenges by leveraging Protocol Buffers as the intermediate representation between GraphQL and consumption interfaces.

Performance

Protocol Buffer encoding delivers significant efficiency gains over JSON-based GraphQL responses:

Reliability

The architecture inherently improves system reliability through contract enforcement:

Operational Efficiency

The approach eliminates common sources of operational complexity:

API Abstraction

Consumers interact through stable, well-defined interfaces rather than raw query languages:

Security Model

All API paths are explicitly bounded by design:

One API, Multiple Interfaces

The core concept of API Consumption in Cosmo is simple:

GraphQL is your interface for design and governance; RPC and REST are your interfaces for consumption.

Platform teams define collections of Trusted Documents - named GraphQL queries and mutations that represent the supported API surface.

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

This single GetUser operation becomes a versioned RPC method, a REST endpoint and a typed SDK function.

Cosmo compiles these into Protocol Buffer definitions, and the router acts as a mediation layer, automatically mapping incoming RPC or HTTP requests to these trusted operations against your graph. This approach provides:

Benefit Before After
Governance Arbitrary queries allowed in production No arbitrary queries in production - only defined operations are exposed
Type Safety Handwritten clients with runtime shape mismatches No handwritten clients or runtime shape mismatches - strongly typed generated code
Performance POST-only requests bypass HTTP caching GET-based queries unlock HTTP caching and CDNs

How It Works

The lifecycle moves from GraphQL contract definition to multi-protocol consumption, without introducing additional API layers.

1. Define Contracts: Create named GraphQL operations (Trusted Documents) and compile them into Protocol Buffer definitions that act as stable, versioned API contracts. 2. Configure Router: Load the proto definitions into the Cosmo Router, which handles protocol translation automatically without server-side code. 3. Generate & Distribute SDKs: Generate type-safe client SDKs (in languages like Go and TypeScript) and OpenAPI specifications from your definitions, ready for distribution. 4. Consume: Developers install generated SDKs or use standard HTTP clients to interact with the API in their preferred language and protocol.

Supported Protocols and Clients

By defining your operations once, you can support a wide range of consumers:

All interfaces are generated from the same GraphQL operations and stay in sync by construction.

Hands-on Tutorial: The documentation in this section uses examples from our ConnectRPC Tutorial Repository. We recommend cloning it to follow along with the guides.