Introduction
FARP — Forge API Gateway Registration Protocol for schema-aware service discovery
FARP (Forge API Gateway Registration Protocol) is a protocol specification library that enables service instances to communicate their API schemas, health information, and capabilities to API gateways and service meshes. It provides standardized data structures, schema generation tooling, and merging utilities for building schema-aware distributed systems.
Think of FARP like protobuf or openapi-generator — it defines the format and provides tooling, but you implement the transport layer.
What FARP Provides
FARP is a protocol library, not a framework. It provides:
| Component | Description | Package |
|---|---|---|
| Type Definitions | SchemaManifest, SchemaDescriptor, routing/auth configs | types.go |
| Schema Providers | Generate schemas from application code | providers/* |
| Registry Interface | Storage abstraction for backends | registry.go |
| Merging Logic | Compose multiple schemas into unified docs | merger/* |
| Validation | Ensure manifests are spec-compliant | manifest.go |
What FARP Is NOT
- Not an API Gateway — No routing, rate limiting, or traffic management
- Not a Service Framework — Services must implement their own HTTP endpoints
- Not Service Discovery — Extends existing discovery systems (Consul, etcd, K8s, mDNS)
- Not a Backend Implementation — Provides interfaces, not Consul/etcd/K8s clients
Key Features
- Schema-Aware Service Discovery: Services register with complete API contracts
- Multi-Protocol Support: OpenAPI, AsyncAPI, gRPC, GraphQL, oRPC, Thrift, and Avro
- Dynamic Gateway Configuration: API gateways auto-configure routes based on registered schemas
- Health & Telemetry Integration: Built-in health checks and metrics endpoints
- Backend Agnostic: Works with Consul, etcd, Kubernetes, mDNS/Bonjour, Eureka, and custom backends
- Zero-Downtime Updates: Schema versioning and checksum validation
How It Works
┌──────────────────────────────────────────────────────────┐
│ API Gateway / Service Mesh │
│ • Watches for schema updates │
│ • Fetches schemas from registry or HTTP │
│ • Converts schemas to gateway routes │
│ • Monitors service health │
└──────────────────────────┬───────────────────────────────┘
│ Subscribe to manifest changes
┌──────────────────────────▼───────────────────────────────┐
│ Service Discovery Backend │
│ (Consul, etcd, Kubernetes, mDNS/Bonjour, Eureka, etc.) │
└──────────────────────────▲───────────────────────────────┘
│ Register manifest + schemas
┌──────────────────────────┴───────────────────────────────┐
│ Service Instance (Forge App) │
│ • Generates schemas from router (OpenAPI, AsyncAPI) │
│ • Creates SchemaManifest │
│ • Publishes to registry or serves via HTTP │
└──────────────────────────────────────────────────────────┘Quick Start
Installation
go get github.com/xraph/farpCreate a Schema Manifest
package main
import "github.com/xraph/farp"
func main() {
manifest := farp.NewManifest("user-service", "v1.2.3", "instance-abc123")
// Add an OpenAPI schema
manifest.AddSchema(farp.SchemaDescriptor{
Type: farp.SchemaTypeOpenAPI,
SpecVersion: "3.1.0",
ContentType: "application/json",
Location: farp.SchemaLocation{
Type: farp.LocationTypeHTTP,
URL: "http://user-service:8080/openapi.json",
},
Hash: "a1b2c3...", // SHA256 of schema content
Size: 4096,
})
manifest.AddCapability("rest")
manifest.Endpoints.Health = "/health"
manifest.Endpoints.OpenAPI = "/openapi.json"
// Validate the manifest
if err := manifest.Validate(); err != nil {
panic(err)
}
// Serialize to JSON
data, _ := manifest.ToPrettyJSON()
fmt.Println(string(data))
}Use Schema Providers
import (
"github.com/xraph/farp/providers/openapi"
"github.com/xraph/farp/providers/grpc"
"github.com/xraph/farp/providers/graphql"
)
// OpenAPI provider
openapiProvider := openapi.NewProvider("3.1.0", "/openapi.json")
schema, err := openapiProvider.Generate(ctx, app)
// gRPC provider
grpcProvider := grpc.NewProvider("proto3", nil)
schema, err = grpcProvider.Generate(ctx, app)
// GraphQL provider (SDL format)
graphqlProvider := graphql.NewProvider("2021", "/graphql")
graphqlProvider.UseSDL()
schema, err = graphqlProvider.Generate(ctx, app)Supported Protocols
| Protocol | Provider | Spec Version | Content Type |
|---|---|---|---|
| OpenAPI | providers/openapi | 3.1.0 | application/json |
| AsyncAPI | providers/asyncapi | 3.0.0 | application/json |
| gRPC | providers/grpc | proto3 | application/json |
| GraphQL | providers/graphql | 2021 | application/graphql |
| oRPC | providers/orpc | 1.0.0 | application/json |
| Thrift | providers/thrift | 0.19.0 | application/json |
| Avro | providers/avro | 1.11.1 | application/json |
Documentation
Schema Manifest
Core data structures: SchemaManifest, SchemaDescriptor, and endpoints.
Schema Types
Supported schema types, capabilities, and protocol metadata.
Routing
Mount strategies, path rewriting, and authentication configuration.
Schema Providers
Generate schemas from your application code for all supported protocols.
Registry & Storage
Store and retrieve manifests and schemas with backend-agnostic interfaces.
Gateway Integration
Reference gateway client and schema merging for unified API documentation.
How is this guide?