<a href="https://goa.design">
  <img alt="Goa" src="https://goa.design/img/social/goa-banner.png">
</a>






<a href="https://github.com/goadesign/goa/releases/latest"><img alt="Release" src="https://img.shields.io/github/release/goadesign/goa.svg?style=for-the-badge"></a>
<a href="https://pkg.go.dev/goa.design/goa/v3@v3.28.0/dsl?tab=doc"><img alt="Go Doc" src="https://img.shields.io/badge/godoc-reference-blue.svg?style=for-the-badge"></a>
<a href="https://github.com/goadesign/goa/actions/workflows/ci.yml"><img alt="GitHub Action: Test" src="https://img.shields.io/github/actions/workflow/status/goadesign/goa/test.yml?branch=v3&style=for-the-badge"></a>
<a href="https://goreportcard.com/report/github.com/goadesign/goa"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/goadesign/goa?style=for-the-badge"></a>
<a href="https://github.com/goadesign/goa/raw/v3.28.0/LICENSE"><img alt="Software License" src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=for-the-badge"></a>
<a href="https://gurubase.io/g/goa"><img alt="Gurubase" src="https://img.shields.io/badge/Gurubase-Ask%20Goa%20Guru-006BFF?style=for-the-badge"></a>
<a href="https://chat.openai.com/g/g-mLuQDGyro-goa-design-wizard"><img alt="Goa Design Wizard" src="https://img.shields.io/badge/Goa%20Design%20Wizard-ChatGPT-00A67D?logo=openai&logoColor=white&style=for-the-badge"></a>



<a href="https://goadesign.substack.com"><img alt="Substack: Design First" src="https://img.shields.io/badge/Design%20First-Substack-FF6719?logo=substack&logoColor=white&style=for-the-badge"></a>
<a href="https://gophers.slack.com/messages/goa"><img alt="Slack: Goa" src="https://img.shields.io/badge/Goa-Slack-4A154B?logo=slack&logoColor=white&style=for-the-badge"></a>
<a href="https://bsky.app/profile/goadesign.bsky.social"><img alt="Bluesky: Goa Design" src="https://img.shields.io/badge/Goa%20Design-Bluesky-0285FF?logo=bluesky&logoColor=white&style=for-the-badge"></a>

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.

Sponsors

incident.io: Bounce back stronger after every incident Use our platform to empower your team to run incidents end-to-end. Rapidly fix and learn from incidents, so you can build more resilient products. Learn more

Speakeasy: Enterprise DevEx for your API Our platform makes it easy to create feature-rich production ready SDKs. Speed up integrations and reduce errors by giving your API the DevEx it deserves. Integrate with Goa

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               │
└─────────────┘     └──────────────┘     └─────────────────────┘

1. Design: Express your API's intent in Goa's DSL
2. Generate: Run goa gen to create server interfaces, client code, and documentation
3. Implement: Focus solely on writing your business logic in the generated interfaces
4. 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: 1. Defines a simple "hello" service with one method 2. Generates server and client code 3. 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

Using a coding agent with Goa? See skills/ for reusable Agent Skills that help agents follow Goa's design-first workflow in application repositories.

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.