GitHub - goadesign/goa: Design-first Go framework that generates API code, documentation, and clients. Define once in an elegant DSL, deploy as HTTP and gRPC services with zero drift between code and docs. (original) (raw)

Goa

Release Go Doc GitHub Action: Test Go Report Card Software License Gurubase Goa Design Wizard
Substack: Design First Slack: Goa Bluesky: Goa Design

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 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 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:

Goa solves these problems by:

Key Features

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:

Real-World Examples

The examples repository contains complete, working examples demonstrating:

Community & Support

What's New

July 2025: Goa now includes comprehensive JSON-RPC 2.0 support as a first-class transport alongside HTTP and gRPC! Generate complete JSON-RPC services with streaming support (WebSocket and SSE), client/server code, CLI tools, and full type safety - all from a single design.

February 2025: The Goa website has been completely redesigned with extensive new documentation, tutorials, and guides to help you build better services.

Jan 2024: Goa's powerful design DSL is now accessible through theGoa Design Wizard, a specialized AI trained on Goa. Generate service designs through natural language conversations!

License

MIT License - see LICENSE for details.