Overview

​

From GraphQL Operations to Multiple Interfaces

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

/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'

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}`);

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

​

Architectural Benefits

​

Performance

• Compact wire format: Binary serialization reduces payload sizes, lowering bandwidth consumption and improving response times
• Optimized parsing: Generated code eliminates runtime reflection and dynamic parsing overhead
• HTTP caching: GET-based queries enable standard HTTP caching layers and CDN integration

​

Reliability

• Schema-driven validation: All requests are validated against compiled Protocol Buffer definitions before execution
• Deterministic behavior: Trusted Documents eliminate query variability, making performance characteristics predictable
• Infrastructure observability: Standard RPC semantics integrate with existing metrics, tracing, and monitoring infrastructure

​

Operational Efficiency

• No manual glue code: The router handles protocol translation automatically—no custom ingress controllers, API gateways, or translation layers required
• Single source of truth: GraphQL operations define the contract once; all downstream artifacts are generated, not maintained
• Breaking change detection: Schema changes are validated against defined operations at compile time, surfacing incompatibilities before deployment
• Reduced attack surface: Only explicitly defined operations are exposed—arbitrary query construction is not possible at runtime

​

API Abstraction

• No exposed GraphQL: API consumers use generated SDKs or standard REST/RPC calls—they never construct or see GraphQL queries
• Implementation independence: The underlying GraphQL layer becomes an internal implementation detail, not a public contract
• Simplified onboarding: Consumers integrate using familiar patterns (REST, gRPC, typed and generated clients) without GraphQL expertise

​

Security Model

• Enclosed execution paths: Consumers can only invoke operations that have been pre-defined and compiled into the system
• No query injection: Unlike open GraphQL endpoints, there is no mechanism for clients to construct arbitrary queries
• Auditable contracts: Every exposed operation is traceable to a named, versioned definition in source control

​

One API, Multiple Interfaces

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

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.

​

How It Works

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

• REST / HTTP: Simple JSON encoding over HTTP/1.1 or HTTP/2 for universal access via tools like curl.
• OpenAPI/Swagger: Automatically generated specifications for documentation and REST tooling integration.
• Typed SDKs: Generated client libraries for languages like TypeScript, Go, Swift, and Kotlin using standard tools like Buf.
• gRPC: High-performance binary protobuf over HTTP/2 for internal microservices.
• Connect Protocol & gRPC-Web: Browser-compatible RPC protocols.