Goa - Design First, Code With Confidence

Overview

Goa transforms how you build APIs and microservices in Go with its powerful design-first approach. Instead of writing boilerplate code, you express your API's intent through a clear, expressive DSL. Goa then automatically generates production-ready code, comprehensive documentation, and client libraries—all perfectly aligned with your design.

The result? Dramatically reduced development time, consistent APIs, and the elimination of the documentation-code drift that plagues traditional development.

Why Goa?

Traditional API development suffers from:

Inconsistency: Manually maintained docs that quickly fall out of sync with code
Wasted effort: Writing repetitive boilerplate and transport-layer code
Painful integrations: Client packages that need constant updates
Design afterthoughts: Documentation added after implementation, missing key details

Goa solves these problems by:

Generating 30-50% of your codebase directly from your design
Ensuring perfect alignment between design, code, and documentation
Supporting multiple transports (HTTP, gRPC, and JSON-RPC) from a single design
Maintaining a clean separation between business logic and transport details

Key Features

Expressive Design Language: Define your API with a clear, type-safe DSL that captures your intent
Comprehensive Code Generation:
- Type-safe server interfaces that enforce your design
- Client packages with full error handling
- Transport layer adapters (HTTP/gRPC/JSON-RPC) with routing and encoding
- OpenAPI/Swagger documentation that's always in sync
- CLI tools for testing your services
Multi-Protocol Support: Generate HTTP REST, gRPC, and JSON-RPC endpoints from a single design
Clean Architecture: Business logic remains separate from transport concerns
Enterprise Ready: Supports authentication, authorization, CORS, logging, and more
Comprehensive Testing: Includes extensive unit and integration test suites ensuring quality and reliability

How It Works

┌─────────────┐     ┌──────────────┐     ┌─────────────────────┐
│ Design API  │────>│ Generate Code│────>│ Implement Business  │
│ using DSL   │     │ & Docs       │     │ Logic               │
└─────────────┘     └──────────────┘     └─────────────────────┘

Design: Express your API's intent in Goa's DSL
Generate: Run goa gen to create server interfaces, client code, and documentation
Implement: Focus solely on writing your business logic in the generated interfaces
Evolve: Update your design and regenerate code as your API evolves

Quick Start

# Install Goa
go install goa.design/goa/v3/cmd/goa@latest

# Create a new module
mkdir hello && cd hello
go mod init hello

# Define a service in design/design.go
mkdir design
cat > design/design.go << EOF
package design

import . "goa.design/goa/v3/dsl"

var _ = Service("hello", func() {
    Method("say_hello", func() {
        Payload(func() {
            Field(1, "name", String)
            Required("name")
        })
        Result(String)

        HTTP(func() {
            GET("/hello/{name}")
        })
    })
})
EOF

# Generate the code
goa gen hello/design
goa example hello/design

# Build and run
go mod tidy
go run cmd/hello/*.go --http-port 8000

# In another terminal
curl http://localhost:8000/hello/world

The example above:

Defines a simple "hello" service with one method
Generates server and client code
Starts a server that logs requests server-side (without displaying any client output)

JSON-RPC Alternative

For a JSON-RPC service, simply add a JSONRPC expression to the service and method:

var _ = Service("hello" , func() {
    JSONRPC(func() {
        Path("/jsonrpc")
    })
    Method("say_hello", func() {
        Payload(func() {
            Field(1, "name", String)
            Required("name")
        })
        Result(String)

        JSONRPC(func() {})
    })
}

Then test with:

curl -X POST http://localhost:8000/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"hello.say_hello","params":{"name":"world"},"id":"1"}'

Documentation

Our documentation site at goa.design provides comprehensive guides and references:

Introduction: Understand Goa's philosophy and benefits
Getting Started: Build your first Goa service step-by-step
Tutorials: Learn to create REST APIs, gRPC services, and more
Core Concepts: Master the design language and architecture
Real-World Guide: Follow best practices for production services
Advanced Topics: Explore advanced features and techniques

Real-World Examples

The examples repository contains complete, working examples demonstrating:

Basic: Simple service showcasing core Goa concepts
Cellar: A more complete REST API example
Cookies: HTTP cookie management
Encodings: Working with different content types
Error: Comprehensive error handling strategies
Files & Upload/Download: File handling capabilities
HTTP Status: Custom status code handling
Interceptors: Request/response processing middleware
Multipart: Handling multipart form submissions
Security: Authentication and authorization examples
Streaming: Implementing streaming endpoints (HTTP, WebSocket, JSON-RPC SSE)
Tracing: Integrating with observability tools
TUS: Resumable file uploads implementation

Community & Support

Join the #goa channel on Gophers Slack
Ask questions on GitHub Discussions
Follow us on Bluesky
Report issues on GitHub
Find answers with the Goa Guru AI assistant
Subscribe to our Substack, “Design First”: Design First

License

MIT License - see LICENSE for details.

Goa

Install / Use

README